APIの概要

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

Braze REST APIコレクション

API定義

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

エンドポイント

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

BrazeでRESTエンドポイントを見つけるには：

1. Brazeにログインし、Settings > APIs and Identifiers > API Keysに移動します。
2. 既存のAPIキーを選択するか、Create API Keyを選択して新しいキーを作成します。
3. このタブに表示されているRESTエンドポイントをコピーし、APIリクエストにそのエンドポイントを使用します。

重要

API呼び出しにエンドポイントを使用する場合は、RESTエンドポイントを使用してください。

SDK統合には、RESTエンドポイントではなくSDKエンドポイントを使用してください。

API制限

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

ユーザーID

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

詳細については、iOS、Android、Webの各プラットフォームに応じた以下の記事を参照してください。

REST APIキーについて

RESTアプリケーションAPIキー（REST APIキー）とは、API呼び出しを認証し、呼び出し元となるアプリケーションやユーザーを識別するためにAPIに渡す一意のコードです。貴社のREST APIエンドポイントに対してHTTPSウェブリクエストを送信することで、APIにアクセスします。REST APIキーは、App Identifierキーと連携してデータのトラッキング、アクセス、送信、エクスポート、分析を行い、すべてが円滑に動作していることを保証するのに役立ちます。

ワークスペースと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からアプリ、テンプレート、Canvases、Campaigns、Content Cards、Segmentsといった特定のものを参照するために使用できます。詳細については、API識別子のタイプを参照してください。

REST APIキーを作成する

新しいREST APIキーを作成するには：

1. Settings > APIs and Identifiersに移動します。
2. Create API Keyを選択します。
3. 一目で識別できるように、新しいキーに名前をつけます。
4. 新しいキーに対して許可リストに登録するIPアドレスとサブネットを指定します。
5. 新しいキーに関連付ける権限を選択します。

重要

新しいAPIキーを作成した後は、権限の範囲や許可リストに登録済みのIPを編集できないことに留意してください。この制限はセキュリティ上の理由から設けられています。キーのスコープを変更する必要がある場合は、更新された権限を持つ新しいキーを作成し、古いキーの代わりにそのキーを実装してください。実装が完了したら、古いキーを削除できます。

REST APIキーの権限

APIキーの権限は、特定のAPI呼び出しへのアクセスを制限するために、ユーザーまたはグループに割り当てることができる権限です。APIキーの権限のリストを表示するには、Settings > APIs and Identifiersと進み、APIキーを選択します。

• user data
• email
• messages
• campaigns
• canvas
• segments
• purchases
• events
• sessions
• kpis
• templates
• sso
• content blocks
• preference center
• subscription
• sms
• catalogs
• sdk authentication

REST APIキーを管理する

Settings > APIs and Identifiers > API Keysタブから、既存のREST APIキーの詳細を表示したり、削除したりできます。REST APIキーは作成後に編集できないことに注意してください。

API Keysタブには、各キーについて以下の情報が含まれています：

APIキーの詳細を表示するには、キーにカーソルを合わせて Viewを選択します。これには、このキーが持つすべての権限、ホワイトリストに登録されているIP（もしあれば）、このキーがBraze IPホワイトリストにオプトインしているかどうかが含まれます。

ユーザーを削除する際、Brazeはそのユーザーが作成した関連するAPIキーを削除しないことに注意してください。キーを削除するには、キーにカーソルを合わせて Deleteを選択します。

REST APIキーのセキュリティ

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

REST APIキーによって潜在的に機密性の高いREST APIエンドポイントへのアクセスが許可されるため、これらのキーを安全に保管し、信頼できるパートナーとのみ共有してください。これらのキーは一般公開しないでください。例えば、このキーを使ってWebサイトからAJAX呼び出しを行ったり、その他の公開的な方法で公開してはいけません。

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

警告

REST APIキーは、潜在的にセンシティブなREST APIエンドポイントへのアクセスを可能にするものであることを考慮し、安全に保管・使用されていることを確認してください。例えば、このキーを使ってWebサイトからAJAX呼び出しを行ったり、その他の公開的な方法で公開してはいけません。

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

REST APIキーとSDK APIキーのセキュリティ

REST APIキーとSDK APIキーは、セキュリティプロファイルが異なります。

API IPの許可リスト

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

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

ヒント

Braze to Braze Webhookを作成し、許可リストを使用する場合は、ホワイトリストに登録するIPアドレスのリストを参照してください。

API認証とセキュリティ

ベアラートークン認証

Brazeは、Authorizationリクエストヘッダーにベアラートークンとして渡されたREST APIキーを使用して、REST APIリクエストを認証します。リクエストを送信する際は、APIキーを次の形式で含めてください：

1
Authorization: Bearer YOUR_REST_API_KEY

各リクエストに対して、Brazeは以下のサーバーサイド検証チェックを実行します：

1. トークンの有効性： REST APIキーがBrazeに存在し、有効であることを確認します（例えば、失効または無効化されていない状態であること）。
2. トークンの認可： APIキーが要求されたエンドポイントに必要な権限を持っていることを確認します。

認証が失敗した場合、APIはHTTPステータスコード付きのエラー応答を返します。例えば、401 Unauthorizedはキーが無効または欠落していることを示し、403 Forbiddenはキーが要求されたエンドポイントに対する権限を持っていないことを示します。詳細については、APIエラーを参照してください。

ネットワークレベルのセキュリティ

BrazeへのREST APIリクエストは、リクエストパス全体でトランスポート層セキュリティ（TLS）暗号化によって保護されています。以下の表は、お客様のサーバーからBrazeへのAPIリクエストのネットワークフローを説明するものです：

TLS暗号化は、チェーンのすべてのリンクをカバーします。お客様のサーバーはTLS経由でCloudflareに接続し、CloudflareはNLBを介してNGINXイングレスへ別のTLS接続を確立するため、APIキーとリクエストデータは転送中に暗号化されたままとなります。

その他のリソース

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

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

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

重要

このクライアントライブラリーはベータ版です。このライブラリーをより良くするために、フィードバックを[email protected]宛にお送りください。