Skip to content

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制限

ほとんどの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アプリケーション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キーが認証できる呼び出しを厳密に制限できます。

APIキータブにあるREST APIキーのパネル。

REST APIキーを作成する

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

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

REST APIキーの権限

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

REST APIキーを管理する

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

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

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

Brazeダッシュボードの APIキー権限のリスト。

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

ゴミ箱のアイコンが強調表示され、「削除」を示す「Last Seen」というAPIキー。

REST APIキーのセキュリティ

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

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

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

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

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

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

API IPの許可リスト

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

APIキーの作成時にIPを許可リストに登録するオプション。

何も指定しない場合、すべての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クライアントライブラリーは、ユーザーエンドポイントをサポートしています。
Github   GitHub でこのページを編集
New Stuff!