APIの概要
このリファレンス記事では、一般的な用語やREST API キーの概要、権限、セキュリティ保護の方法など、API の基本について説明します。
API定義
以下に、Braze REST API のドキュメントに記載されている用語の概要を示します。
エンドポイント
Braze は、ダッシュボードおよびREST エンドポイントのさまざまなインスタンスを管理します。アカウントがプロビジョニングされると、次のいずれかのURL にログインします。プロビジョニング先のインスタンスに基づいて、正しいREST エンドポイントを使用します。不明な場合は、support ticket を開くか、次の表を使用して、使用するダッシュボードのURL を正しいREST エンドポイントに一致させます。
API コールにエンドポイントを使用する場合は、REST エンドポイントを使用します。
SDK 統合では、REST エンドポイントではなく、SDK エンドポイント を使用します。
| インスタンス | 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キーは、アプリIDキーと連動して使用し、データの追跡、アクセス、送信、エクスポート、分析を行い、お客様と弊社の両方ですべてがスムーズに実行されるようにします。
ワークスペースとAPI キーは、Braze の手元にあります。ワークスペースは、複数のプラットフォームにまたがって同じアプリケーションのバージョンを格納するように設計されています。また、多くのお客様は、ワークスペースを使用して、同じプラットフォーム上にアプリケーションの無料およびプレミアムバージョンを格納します。気付くかもしれないが、これらのワークスペースはREST API も使用しており、独自のREST API キーを持っている。これらのキーに個別のスコープを設定すれば、API 上の特定のエンドポイントにアクセスできるようになります。API の呼び出しには必ず、エンドポイントへのアクセス権を持つキーを含める必要があります。
REST API キーとワークスペースAPI キーの両方をapi_key と呼びます。api_key は、リクエストヘッダーとして各リクエストに含まれ、REST API を使用できる認証キーとして機能します。これらのREST API は、ユーザーの追跡、メッセージの送信、ユーザーデータのエクスポートなどに使用されます。新しいREST API キーを作成するときは、特定のエンドポイントにアクセスできるようにする必要があります。API キーに特定の権限を割り当てることで、API キーを呼び出すことで認証できるコールを厳密に制限できます。
REST API キーに加えて、アプリ、テンプレート、キャンバス、キャンペーン、コンテンツカード、API のセグメントなど、特定のものを参照するために使用できるIdentifier キーと呼ばれるキーのタイプもあります。詳細については、API Identifier typesを参照してください。
REST API キー権限
API キーパーミッションは、特定のAPI コールへのアクセスを制限するためにユーザーまたはグループに割り当てることができるパーミッションです。API キー権限のリストを表示するには、Settings > API Keys に移動し、API キーを選択します。
| 権限 | エンドポイント | 説明 |
|---|---|---|
users.track |
/users/track |
Rユーザー属性、カスタムイベント、および購入を記録します。 |
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 |
既存のユーザーの external 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 |
ブロックリストの電子メールアドレス。 |
| 権限 | エンドポイント | 説明 |
|---|---|---|
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 |
Transactional メッセージングエンドポイントを使用してトランザクションメッセージングを送信できるようにします。 |
| 権限 | エンドポイント | 説明 |
|---|---|---|
canvas.trigger.send |
/canvas/trigger/send |
既存のキャンバスの送信をトリガします。 |
canvas.trigger.schedule.create |
/canvas/trigger/schedule/create |
今後のCanvas の送信を、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 アナリティクスのロールアップのクエリ。 |
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 |
News Feed カードのリストを問い合わせます。 |
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 |
一日に一意のアクティブユーザーのクエリ。 |
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 |
ダッシュボードに新しいメールテンプレートを作成します。 |
templates.email.info |
/templates/email/info |
特定のテンプレートの情報を問い合わせます。 |
templates.email.list |
/templates/email/list |
メールテンプレートのリストのクエリ。 |
templates.email.update |
/templates/email/update |
ダッシュボードに保存されているメールテンプレートを更新します。 |
| 権限 | 説明 |
|---|---|
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 |
List preference centers. |
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} |
既存のカタログから1つのアイテムを置き換えます。 |
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 キーを作成するには
- Settings > API Keys に移動します。このページには、既存のAPI キーが表示されます。
古いナビゲーション を使用している場合は、Developer Console> API Settings からAPI キーを作成できます。
2.+ Create New API Keyをクリックします。 3.新しいキーに一目で識別用の名前を付けます。 4.新しいキーに関連付ける権限を選択します。 5.新しいキーのallowlisted IP addresses とサブネットを指定します。
新しいAPI キーを作成した後は、権限のスコープや許可されたIP を編集できないことに注意してください。この制限は、セキュリティ上の理由から設けられています。キーのスコープを変更する必要がある場合は、更新された権限を持つ新しいキーを作成し、古いキーの代わりにそのキーを実装します。実装が完了したら、古いキーを削除します。
REST API キーの管理
REST API キーは、作成後に編集できませんが、API Keys ページから既存のREST API キーの詳細を表示または削除できます。Rest API Keysリストには、各キーの以下の情報が一覧表示されます。
| フィールド | 説明 |
|---|---|
| API キー名 | 作成時にキーに付けられた名前。 |
| 識別子 | API キー。 |
| 作成者 | キーを作成したユーザのメールアドレス。このフィールドは”N と表示されます/A” for keys created before June 2023. |
| Date Created | The date this key was created. |
| Last Seen | The date this key was last used. This field will show as “N/A” for keys that have never been used. |
特定のキーの詳細を表示するには、リストからキーを選択します。次に、このキーにあるすべての権限、ホワイトリストに登録されたIP(ある場合)、およびこのキーがBraze IP ホワイトリストに選択されているかどうかを確認できます。
キーを削除するには、をクリックし、対応するオプションを選択します。
REST API キーセキュリティ
API キーは、API 呼び出しを認証するために使用されます。新しい REST API キーを作成するときには、特定のエンドポイントへのアクセス権をキーに付与する必要があります。API キーに特定の権限を割り当てることで、API キーを呼び出すことで認証できるコールを厳密に制限できます。
REST API キーを使用すると、機密性が高い可能性のあるREST API エンドポイントへのアクセスが許可されるため、これらのキーを保護し、信頼できるパートナーとのみ共有します。ただしこれらのキーは一般公開しないでください。たとえば、このキーを使用してウェブサイトからAJAX コールを発信したり、他のパブリックな方法で公開したりしないでください。
優れたセキュリティプラクティスは、ジョブを完了するために必要なだけのアクセス権をユーザーに割り当てることです。この原則は、各キーに権限を割り当てることによってAPI キーにも適用できます。これらの権限により、アカウントのさまざまな領域に対するセキュリティとコントロールが向上します。
REST API キーを使用すると、機密性が高い可能性のあるREST API エンドポイントへのアクセスが許可されるため、それらが安全に保存され、使用されていることを確認します。たとえば、このキーを使用してウェブサイトからAJAX コールを発信したり、他のパブリックな方法で公開したりしないでください。
キーの誤露出が発生した場合は、Developer Console から削除できます。このプロセスのヘルプを表示するには、[サポートチケット] [サポート] を開きます。
API IP の許可リスト化
さらなるセキュリティ強化のため、特定の REST API キーに対して REST API 要求が許可されている IP アドレスやサブネットのリストを指定できます。これを許可リスト化またはホワイトリスト化と呼びます。特定の IP アドレスやサブネットを許可するには、新規の REST API キーを作成する際に [ホワイトリスト IP (Whitelist IP)] のセクションにこれらを追加します。
特に指定しない場合は、すべての IP アドレスから要求を送信できます。
Braze 間の Webhook を行う際に許可リストを使用する場合は、ホワイトリスト化が必要な IPのリストをご確認ください。
追加リソース
Rubyクライアントライブラリ
Ruby を使用してBrazeを実装している場合は、Ruby クライアントライブラリ を使用してデータのインポート時間を短縮できます。クライアントライブラリは、1 つのプログラミング言語に固有のコードのコレクションです。この場合、Ruby は、API を使いやすくします。
Ruby クライアントライブラリは、User Endpoints をサポートします。
このクライアントライブラリは現在ベータ版です。私たちがこの図書館をもっと良くするのを手伝ってあげたいですか？[email protected]にご意見をお寄せください。
GitHub でこのページを編集