Skip to content

APIの概要

このリファレンス記事では、一般的な用語、REST API キーや権限の概要、それらを安全に保つ方法など、API の基本について説明します。

Braze REST APIコレクション

コレクション 目的
カタログ Brazeのキャンペーンで参照するカタログやカタログ項目を作成、管理する。
クラウドデータ取り込み データウェアハウスの統合と同期を管理する。
メールリストとアドレス Brazeとお使いのメールシステム間の双方向同期を設定・管理。
エクスポート キャンペーン、キャンバス、KPI などの様々な詳細にアクセスし、エクスポートします。
メッセージ キャンペーンとキャンバスのスケジュールの設定、送信、管理を行います。
ユーザー設定センター ユーザー設定センターを構築し、そのスタイルを更新します。
SCIM クラウドベースのアプリケーションやサービスにおけるユーザーIDを管理する。
SMS サブスクリプショングループでユーザーの電話番号を管理する。
サブスクリプショングループ Brazeダッシュボードに保存されているSMSとEメールの購読グループをリストアップし、更新する。
テンプレート メールメッセージやコンテンツブロックのテンプレートを作成し、更新する。
ユーザーデータ ユーザーを特定し、追跡し、管理する。

API定義

Braze REST API のドキュメントで使用される用語の概要を次に示します。

エンドポイント

Brazeは、ダッシュボードとRESTエンドポイント用のさまざまなインスタンスを管理している。アカウントのプロビジョニングが完了したら、以下のURLのいずれかにログインする。どのインスタンスにプロビジョニングされるかに基づいて、正しいRESTエンドポイントを使用する。不明な場合は、[サポートチケット] [サポート] を開くか、以下の表を使用して、使用するダッシュボードの URL を正しい REST エンドポイントに一致させてください。

インスタンス URL RESTエンドポイント SDKエンドポイント
US-01 https://dashboard-01.braze.com https://rest.iad-01.braze.com sdk.iad-01.braze.com
US-02 https://dashboard-02.braze.com https://rest.iad-02.braze.com sdk.iad-02.braze.com
US-03 https://dashboard-03.braze.com https://rest.iad-03.braze.com sdk.iad-03.braze.com
US-04 https://dashboard-04.braze.com https://rest.iad-04.braze.com sdk.iad-04.braze.com
US-05 https://dashboard-05.braze.com https://rest.iad-05.braze.com sdk.iad-05.braze.com
US-06 https://dashboard-06.braze.com https://rest.iad-06.braze.com sdk.iad-06.braze.com
US-07 https://dashboard-07.braze.com https://rest.iad-07.braze.com sdk.iad-07.braze.com
US-08 https://dashboard-08.braze.com https://rest.iad-08.braze.com sdk.iad-08.braze.com
EU-01 https://dashboard-01.braze.eu https://rest.fra-01.braze.eu sdk.fra-01.braze.eu
EU-02 https://dashboard-02.braze.eu https://rest.fra-02.braze.eu sdk.fra-02.braze.eu

API制限

ほとんどのAPIについて、Brazeはデフォルトで1時間あたり250,000リクエストというレート制限を設けている。しかし、特定のリクエストタイプには、当社の顧客ベース全体で大量のデータをよりよく処理するために、独自のレート制限が適用されます。詳細はAPI レート制限を参照してください。

ユーザー ID

  • External user ID:external_id は、データの送信対象となる一意のユーザー識別子として機能します。この識別子は、同じユーザーに複数のプロファイルが作成されるのを避けるため、Braze SDK で設定したものと同じでなければなりません。
  • BrazeユーザーIDbraze_id は、Brazeが設定する固有のユーザー識別子の役割を果たす。この識別子は、external_idsに加えて、REST APIを通じてユーザーを削除するために使用できる。

詳細については、iOSAndroidWebの各プラットフォームに応じた以下の記事を参照のこと。

REST APIキー

REST Application Programming Interface キー (REST APIキー) は、API 呼び出しを認証し、呼び出し元のアプリケーションまたはユーザーを識別するために API に渡される一意のコードです。APIアクセスは、御社のREST APIエンドポイントへのHTTPSウェブリクエストを使って行われる。Brazeでは、REST APIキーをApp Identifierキーと組み合わせて使用し、データの追跡、アクセス、送信、エクスポート、分析を行い、お客様とBrazeの両エンドですべてがスムーズに進むようサポートする。

Brazeでは、ワークスペースとAPIキーは密接な関係にある。ワークスペースは、複数のプラットフォームにまたがる同じアプリケーションのバージョンを収容するように設計されている。また、多くの顧客はワークスペースを使用して、無料版とプレミアム版のアプリケーションを同じプラットフォーム上に格納しています。お気づきかもしれませんが、これらのワークスペースも REST API を利用しており、独自の REST API キーが存在します。これらのキーは、API上の特定のエンドポイントへのアクセスを含むように、個別にスコープすることができる。API の各呼び出しには、エンドポイントヒットへのアクセス権を持つキーを含める必要があります。

REST API キーとワークスペース API キーの両方をapi_key と呼ぶ。api_key はリクエストヘッダーとして各リクエストに含まれ、REST API を使用するための認証キーとして機能します。これらの REST API は、ユーザーの追跡、メッセージの送信、ユーザーデータのエクスポートなどに使用されます。新しい REST API キーを作成する際には、そのキーに特定のエンドポイントへのアクセス権を与える必要があります。API キーに特定の権限を割り当てることで、API キーが認証できる呼び出しを厳密に制限できます。

![API キーページにある REST API キーのパネル。][27]

REST APIキーのパーミッション

APIキーのパーミッションは、特定のAPIコールへのアクセスを制限するために、ユーザーまたはグループに割り当てることができるパーミッションである。APIキーのパーミッションのリストを表示するには、「Settings(設定)」>「API Keys(APIキー)」と進み、APIキーを選択する。

許可 エンドポイント 説明
users.track /users/track ユーザー属性、カスタムイベント、購入を記録する。
users.delete /users/delete 任意のユーザーを削除する。
users.alias.new /users/alias/new 既存のユーザーのエイリアスを新規作成する。
users.identify /users/identify 外部IDを持つエイリアスのみのユーザーを特定する。
users.export.ids /users/export/ids ユーザー ID でユーザープロファイル情報を照会します。
users.export.segment /users/export/segment セグメント別のユーザープロファイル情報を照会する。
users.merge /users/merge 既存の2人のユーザーを互いにマージする。
users.external_ids.rename /users/external_ids/rename 既存のユーザーの外部IDを変更する。
users.external_ids.remove /users/external_ids/remove 既存のユーザーの外部IDを削除する。
users.alias.update /users/alias/update 既存のユーザーのエイリアスを更新する。
users.export.global_control_group /users/export/global_control_group グローバルコントロールグループのユーザープロファイル情報を照会する。
許可 エンドポイント 説明
email.unsubscribe /email/unsubscribes 配信停止になっているメールアドレスを照会します。
email.status /email/status メールアドレスのステータスを変更する。
email.hard_bounces /email/hard_bounces ハードバウンスされたメールアドレスを照会します。
email.bounce.remove /email/bounce/remove ハードバウンスリストからメールアドレスを削除します。
email.spam.remove /email/spam/remove スパムリストからメールアドレスを削除する。
email.blacklist /email/blacklist ブロックリストのメールアドレス。
許可 エンドポイント 説明
messages.send /messages/send 特定のユーザーに即座にメッセージを送る。
messages.schedule.create /messages/schedule/create 特定の時間にメッセージを送信するようスケジュールする。
messages.schedule.update /messages/schedule/update スケジュールされたメッセージを更新する。
messages.schedule.delete /messages/schedule/delete スケジュールされたメッセージを削除する。
messages.schedule_broadcasts /messages/scheduled_broadcasts スケジュールされたすべてのブロードキャストメッセージを問い合わせる。
messages.live_activity.update /messages/live_activity/update iOSのライブアクティビティを更新する。
許可 エンドポイント 説明
campaigns.trigger.send /campaigns/trigger/send 既存のキャンペーンの送信をトリガーする。
campaigns.trigger.schedule.create /campaigns/trigger/schedule/create API トリガー配信でキャンペーンの将来の送信をスケジュールします。
campaigns.trigger.schedule.update /campaigns/trigger/schedule/update APIトリガー配信でスケジュールされたキャンペーンを更新する。
campaigns.trigger.schedule.delete /campaigns/trigger/schedule/delete APIトリガー配信でスケジュールされたキャンペーンを削除する。
campaigns.list /campaigns/list キャンペーンの一覧を問い合わせる。
campaigns.data_series /campaigns/data_series 時間範囲のキャンペーン分析を照会する。
campaigns.details /campaigns/details 特定のキャンペーンの詳細を問い合わせる。
sends.data_series /sends/data_series 特定の期間のメッセージ送信分析を照会します。
sends.id.create /sends/id/create メッセージブラスト追跡用の送信IDを作成する。
campaigns.url_info.details /campaigns/url_info/details キャンペーン内の特定のメッセージバリエーションのURL詳細を問い合わせる。
transactional.send /transactional/v1/campaigns/{campaign_id}/send トランザクションメッセージングエンドポイントを使用してトランザクションメッセージングを送信できるようにします。
許可 エンドポイント 説明
canvas.trigger.send /canvas/trigger/send 既存のキャンバスの送信をトリガーする。
canvas.trigger.schedule.create /canvas/trigger/schedule/create API トリガー配信を使用してキャンバスの今後の送信をスケジュールします。
canvas.trigger.schedule.update /canvas/trigger/schedule/update APIトリガー配信でスケジュールされたキャンバスを更新する。
canvas.trigger.schedule.delete /canvas/trigger/schedule/delete APIトリガー配信でスケジュールされたキャンバスを削除する。
canvas.list /canvas/list キャンバスのリストを問い合わせる。
canvas.data_series /canvas/data_series 特定の期間のキャンバス分析を照会します。
canvas.details /canvas/details 特定のキャンバスの詳細を照会します。
canvas.data_summary /canvas/data_summary 特定の期間のキャンバス分析のロールアップを照会します。
canvas.url_info.details /canvas/url_info/details キャンバスステップ内の特定のメッセージバリエーションの URL 詳細を照会します。
許可 エンドポイント 説明
segments.list /segments/list セグメントのリストを問い合わせる。
segments.data_series /segments/data_series 時間範囲のセグメント分析を照会する。
segments.details /segments/details 特定のセグメントの詳細を問い合わせる。
許可 エンドポイント 説明
purchases.product_list /purchases/product_list アプリで購入した商品のリストを問い合わせる。
purchases.revenue_series /purchases/revenue_series 時間範囲にわたって、アプリで1日あたりに使われた金額の合計を照会する。
purchases.quantity_series /purchases/quantity_series 特定の期間内の、1日あたりのアプリ内購入数の合計を照会します。
許可 エンドポイント 説明
events.list /events/list カスタムイベントのリストを問い合わせる。
events.data_series /events/data_series 時間範囲にわたるカスタムイベントの発生を問い合わせる。
許可 エンドポイント 説明
feed.list /feed/list ニュースフィードカードの一覧を問い合わせる。
feed.data_series /feed/data_series ニュースフィードの分析を時間範囲にわたって照会する。
feed.details /feed/details 特定のニュースフィードの詳細を問い合わせる。
許可 エンドポイント 説明
sessions.data_series /sessions/data_series 時間範囲内の1日あたりのセッションを問い合わせる。
許可 エンドポイント 説明
kpi.dau.data_series /kpi/dau/data_series 特定の期間内の、1日あたりの固有のアクティブユーザー数を照会します。
kpi.mau.data_series /kpi/mau/data_series 特定の期間内の、30日間ごとの固有のアクティブユーザー数の合計を照会します。
kpi.new_users.data_series /kpi/new_users/data_series 特定の期間内の、1日あたりの新規ユーザー数を照会します。
kpi.uninstalls.data_series /kpi/uninstalls/data_series 時間範囲における1日あたりのアプリのアンインストールを問い合わせる。
許可 エンドポイント 説明
templates.email.create /templates/email/create ダッシュボードで新しいEメールテンプレートを作成する。
templates.email.info /templates/email/info 特定のテンプレートの情報を問い合わせる。
templates.email.list /templates/email/list Eメールテンプレートのリストを問い合わせる。
templates.email.update /templates/email/update ダッシュボードに保存されているEメールテンプレートを更新する。
許可 説明
sso.saml.login ID プロバイダーが開始するログインをセットアップします。詳細については、サービスプロバイダー (SP) が開始するログインを参照してください。
許可 エンドポイント 説明
content_blocks.info /content_blocks/info 特定のテンプレートの情報を問い合わせる。
content_blocks.list /content_blocks/list コンテンツ・ブロックのリストを問い合わせる。
content_blocks.create /content_blocks/create ダッシュボードに新しいコンテンツブロックを作成する。
content_blocks.update /content_blocks_update ダッシュボード上の既存のコンテンツブロックを更新する。
許可 エンドポイント 説明
preference_center.get /preference_center/v1/{preferenceCenterExternalId} ユーザー設定センターを取得します。
preference_center.list /preference_center/v1/list ユーザー設定センターをリストアップします。
preference_center.update /preference_center/v1

/preference_center/v1/{preferenceCenterExternalID}
ユーザー設定センターを作成または更新します。
preference_center.user.get /preference_center/v1/{preferenceCenterExternalId}/url/{userId} ユーザー用のユーザー設定センターリンクを取得します。
許可 エンドポイント 説明
subscription.status.set /subscription/status/set サブスクリプショングループのステータスを設定します。
subscription.status.get /subscription/status/get サブスクリプショングループのステータスを取得する。
subscription.groups.get /subscription/user/status 特定のユーザーが明示的にサブスクライブおよびアンサブスクライブしているサブスクリプショングループのステータスを取得する。
許可 エンドポイント 説明
sms.invalid_phone_numbers /sms/invalid_phone_numbers 無効な電話番号を照会します。
sms.invalid_phone_numbers.remove /sms/invalid_phone_numbers/remove ユーザーから無効な電話番号フラグを削除する。
許可 エンドポイント 説明
catalogs.add_items /catalogs/{catalog_name}/items 既存のカタログに複数のアイテムを追加する。
catalogs.update_items /catalogs/{catalog_name}/items 既存のカタログの複数の項目を更新する。
catalogs.delete_items /catalogs/{catalog_name}/items 既存のカタログから複数の項目を削除する。
catalogs.get_item /catalogs/{catalog_name}/items/{item_id} 既存のカタログから単一の項目を取得する。
catalogs.update_item /catalogs/{catalog_name}/items/{item_id} 既存のカタログの単一項目を更新する。
catalogs.create_item /catalogs/{catalog_name}/items/{item_id} 既存のカタログに単一の項目を作成する。
catalogs.delete_item /catalogs/{catalog_name}/items/{item_id} 既存のカタログから単一の項目を削除する。
catalogs.replace_item /catalogs/{catalog_name}/items/{item_id} 既存のカタログから単一の項目を置き換える。
catalogs.create /catalogs カタログを作成する。
catalogs.get /catalogs カタログのリストを入手する
catalogs.delete /catalogs/{catalog_name} カタログを削除する。
catalogs.get_items /catalogs/{catalog_name}/items 既存のカタログからアイテムのプレビューを取得する。
catalogs.replace_items /catalogs/{catalog_name}/items 既存のカタログのアイテムを置き換える。

REST APIキーを作成する

新しいREST APIキーを作成する:

  1. [設定] > [API と識別子] に進みます。

2.[API キーを作成] を選択します。 3.一目で識別できるように、新しいキーに名前をつける。 4.新しいキーに対して許可リストに登録済みの IPアドレスとサブネットを指定します。

  1. 新しいキーに関連付ける権限を選択します。

REST API キーを管理する

REST APIキーは、作成後に編集することはできない。ただし、API Keysページから、既存のREST APIキーの詳細を見たり、削除したりすることはできる。REST APIキーのリストには、各キーについて以下の情報が一目でわかるようになっています:

フィールド 説明
APIキー名 作成時にキーにつけられた名前。
識別子 APIキー。
作成者 鍵を作成したユーザーのメールアドレス。このフィールドは、2023年6月以前に作成された鍵については「N/A」と表示される。
作成日 このキーが作成された日付。
最終閲覧日 このキーが最後に使われた日付。使用されていないキーの場合、このフィールドには「N/A」と表示されます。

特定のキーの詳細を表示するには、リストからキーを選択する。すると、このキーが持つすべての権限、ホワイトリストに登録されているIP(もしあれば)、このキーがBraze IPホワイトリストに登録されているかどうかを確認できる。

![][30]

ユーザーを削除する場合、そのユーザーが作成した関連APIキーは削除されないことに注意すること。キーを削除するには、 をクリックし、対応するオプションを選択する。

![][29]

REST APIキーのセキュリティ

APIキーは、APIコールを認証するために使用される。新しい REST API キーを作成するときには、特定のエンドポイントへのアクセス権をキーに付与する必要があります。API キーに特定の権限を割り当てることで、API キーが認証できる呼び出しを厳密に制限できます。

REST API キーによって潜在的に機密性の高い REST API エンドポイントへのアクセスが許可される場合は、これらのキーをセキュリティで保護し、信頼できるパートナーとのみ共有します。これらのキーは一般公開しないでください。例えば、このキーを使ってウェブサイトからAJAXコールを行ったり、その他の一般的な方法で公開したりしてはならない。

適切なセキュリティープラクティスは、ジョブを完了するために必要なアクセス権のみをユーザーに割り当てることです。この原則は、各キーに権限を割り当てることによって API キーにも適用できます。これらのアクセス許可により、セキュリティが向上し、アカウントのさまざまな領域をコントロールできます。

APIキーの作成時に利用できるAPIキーの権限。

キーが誤って公開された場合は、開発者コンソールから削除できます。このプロセスに関するヘルプについては、[サポートチケット] [サポート] を開きます。

API IP の許可リスト

セキュリティをさらに強化するため、特定の REST API キーに対して REST API 要求を実行できる IP アドレスやサブネットのリストを指定できます。これは、許可リストまたはホワイトリストと呼ばれます。特定のIPアドレスやサブネットを許可するには、新しいREST APIキーを作成する際に、Whitelist IPsセクションに追加する:

APIキーの作成時にIPをホワイトリストに登録するオプションが追加された。

何も指定しない場合、すべての IP アドレスからリクエストを送信できます。

その他のリソース

Rubyクライアント・ライブラリ

Ruby を使用してBrazeを実装している場合は、Ruby クライアントライブラリ を使用してデータのインポート時間を短縮できます。クライアント・ライブラリとは、あるプログラミング言語(この場合はRuby)に特化したコードの集まりで、APIを使いやすくするものだ。

Ruby クライアントライブラリは、ユーザーエンドポイントをサポートしています。

[support] : /docs/ja/braze_support/ [28]: /docs/ja/assets/img_archive/create-new-key.png?c946be26e03a7d399c1ee05bbbf811d9 [29]: /docs/ja/assets/img_archive/api-key-options.png?8ed31146d679baf4a4a5974ad8c17923 [27]: /docs/ja/assets/img_archive/rest-api-key.png?842dc6972dfb265bb1753e6f4f1b138f [30]: /docs/ja/assets/img_archive/view-api-key.png?3d0fa48c855271f5f64687315bc1c955

「このページはどの程度役に立ちましたか?」
New Stuff!