APIの概要

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

Braze REST APIコレクション

API定義

以下は、Braze REST APIドキュメントで使用される用語の概要です。

エンドポイント

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

BrazeでRESTエンドポイントを確認するには:

1. Brazeにログインし、設定 > APIと識別子 > APIキーに移動します。
2. 既存のAPIキーを選択するか、APIキーを作成を選択して新しいキーを作成します。
3. このタブに表示されるRESTエンドポイントをコピーし、APIリクエストに使用します。

重要

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

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

APIの制限

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

ユーザー ID

• external ID: external_idは、データを送信する対象のユーザーを一意に識別するための識別子です。この識別子は、同じユーザーに対して複数のプロファイルが作成されないようにするため、Braze SDKで設定したものと同じである必要があります。
• Braze ユーザー ID: braze_idは、Brazeが設定する一意のユーザー識別子です。この識別子を使用して、external_idに加えてREST APIを通じてユーザーを削除できます。

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

REST APIキーについて

REST Application Programming Interface キー（REST APIキー）は、APIに渡してAPI呼び出しを認証し、呼び出し元のアプリケーションまたはユーザーを識別する固有のコードです。APIへのアクセスは、会社のREST APIエンドポイントへのHTTPS Webリクエストを使用して行います。REST APIキーはアプリ識別子キーと連携して、データのトラッキング、アクセス、送信、エクスポート、分析を行い、すべてがスムーズに稼働していることを確認します。

ワークスペースと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キーに加えて、アプリ、テンプレート、キャンバス、キャンペーン、Content Cards、セグメントなどの特定のものをAPIから参照するために使用できる識別子キーと呼ばれるタイプのキーも存在します。詳細については、API識別子の種類を参照してください。

REST APIキーの作成

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

1. 設定 > APIと識別子 に移動します。
2. APIキーを作成 を選択します。
3. 一目で識別できるように新しいキーに名前を付けます。
4. 新しいキーの許可リストに登録するIPアドレスとサブネットを指定します。
5. 新しいキーに関連付ける権限を選択します。

重要

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

REST APIキーの権限

APIキーの権限は、特定のAPI呼び出しへのアクセスを制限するためにユーザーまたはグループに割り当てることができる権限です。APIキーの権限一覧を表示するには、設定 > APIと識別子 に移動し、APIキーを選択します。

• ユーザーデータ
• メール
• メッセージ
• キャンペーン
• キャンバス
• セグメント
• 購入
• イベント
• セッション
• kpis
• テンプレート
• sso
• content blocks
• ユーザー設定センター
• 購読
• sms
• カタログ
• sdk認証

REST APIキーの管理

既存のREST APIキーの詳細を表示したり、削除するには、設定 > APIと識別子 > APIキー タブに移動します。REST APIキーは作成後に編集できないことにご注意ください。

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

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

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

REST APIキーのセキュリティ

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

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

良いセキュリティの実践方法は、ユーザーに業務遂行に必要な最小限のアクセスのみを割り当てることです。この原則は、各キーに権限を割り当てることでAPIキーにも適用できます。これらの権限により、アカウントのさまざまな領域に対するセキュリティとコントロールが向上します。

警告

REST APIキーは機密性の高いREST APIエンドポイントへのアクセスを許可する可能性があるため、安全に保存・使用されるようにしてください。たとえば、WebサイトからのAJAX呼び出しにこのキーを使用したり、その他の公開方法でキーを公開したりしないでください。

誤ってキーを公開してしまった場合は、Developer Consoleからキーを削除できます。このプロセスについてサポートが必要な場合は、サポートチケットを開いてください。

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

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

API IP許可リスト

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

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

ヒント

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

API認証とセキュリティ

Bearerトークン認証

Brazeは、AuthorizationリクエストヘッダーにBearerトークンとして渡される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エラーを参照してください。

リクエストヘッダーの大文字・小文字

HTTPヘッダー名は大文字・小文字を区別しないため、Authorizationとauthorizationは同等です。Content-Typeなどの他の標準リクエストヘッダーについても同様です。お使いのHTTPクライアントが生成する大文字・小文字のいずれでも送信できます。

BrazeはBearerスキームのいずれの大文字・小文字表記（Bearer、bearer、BEARER）も受け付けます。REST APIキー自体は、発行されたとおりに正確に送信してください。

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

BrazeへのREST APIリクエストは、リクエストパス全体にわたってTransport Layer Security（TLS）暗号化によって保護されます。以下の表は、サーバーからBrazeへのAPIリクエストのネットワークフローを示しています。

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

その他のリソース

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

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

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

重要

このクライアントライブラリはベータ版です。このライブラリの改善にご協力いただける場合は、[email protected] までフィードバックをお送りください。