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ユーザーID：
braze_idは、Brazeが設定する固有のユーザー識別子の役割を果たす。この識別子は、external_idsに加えて、REST APIを通じてユーザーを削除するために使用できる。
詳細については、iOS、Android、Webの各プラットフォームに応じた以下の記事を参照のこと。
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 識別子のタイプを参照してください。
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 |
時間範囲にわたるカスタムイベントの発生を問い合わせる。 |
ニュースフィードは非推奨になります。Braze では、News Feed ツールを使用するお客様は、コンテンツカードメッセージングチャネルに移動することを推奨しています。これは、より柔軟でカスタマイズ可能で、信頼性が高いチャネルです。詳しくはマイグレーションガイドをご覧ください。
| 許可 | エンドポイント | 説明 |
|---|---|---|
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キーを作成する：
- [設定] ＞ [API と識別子] に進みます。
古いナビゲーションを使用している場合は、[開発者コンソール] > [API 設定] から API キーを作成できます。
2.[API キーを作成] を選択します。 3.一目で識別できるように、新しいキーに名前をつける。 4.新しいキーに対して許可リストに登録済みの IPアドレスとサブネットを指定します。
- 新しいキーに関連付ける権限を選択します。
新しい API キーを作成した後は、権限の範囲や許可リストに登録済みの IP を編集できないことに留意してください。この制限はセキュリティ上の理由から設けられている。キーのスコープを変更する必要がある場合は、更新されたパーミッションを持つ新しいキーを作成し、古いキーの代わりにそのキーを実装する。実装が完了したら、古いキーを削除する。
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 キーにも適用できます。これらのアクセス許可により、セキュリティが向上し、アカウントのさまざまな領域をコントロールできます。
REST APIキーは、潜在的にセンシティブなREST APIエンドポイントへのアクセスを可能にするものであることを考慮し、それらが安全に保管され、使用されることを確認すること。例えば、このキーを使ってウェブサイトからAJAXコールを行ったり、その他の一般的な方法で公開したりしてはならない。
キーが誤って公開された場合は、開発者コンソールから削除できます。このプロセスに関するヘルプについては、[サポートチケット] [サポート] を開きます。
API IP の許可リスト
セキュリティをさらに強化するため、特定の REST API キーに対して REST API 要求を実行できる IP アドレスやサブネットのリストを指定できます。これは、許可リストまたはホワイトリストと呼ばれます。特定のIPアドレスやサブネットを許可するには、新しいREST APIキーを作成する際に、Whitelist IPsセクションに追加する：
何も指定しない場合、すべての IP アドレスからリクエストを送信できます。
Braze to Braze webhook を作成し、許可リストを使用する場合は、ホワイトリストに追加する IP のリストを確認してください。
その他のリソース
Rubyクライアント・ライブラリ
Ruby を使用してBrazeを実装している場合は、Ruby クライアントライブラリ を使用してデータのインポート時間を短縮できます。クライアント・ライブラリとは、あるプログラミング言語（この場合はRuby）に特化したコードの集まりで、APIを使いやすくするものだ。
Ruby クライアントライブラリは、ユーザーエンドポイントをサポートしています。
このクライアントライブラリは現在ベータ版です。このライブラリをより良いものにするために協力してくれませんか?ご意見、ご感想は[email protected] まで。
[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
GitHub でこのページを編集