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が設定する一意のbraze_idユーザー識別子として機能する。この識別子を使って、REST APIを通じてユーザーを削除できる。 external_ids.

詳細については、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キーを作成する

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

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

REST APIキーのパーミッション

APIキーのパーミッションは、特定のAPIコールへのアクセスを制限するために、ユーザーまたはグループに割り当てることができるパーミッションである。API キーのパーミッションのリストを表示するには、[設定] > [API および識別子] と進み、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 キーを管理する

設定＞APIと識別子＞APIキータブから、既存のREST APIキーの詳細を見たり、削除したりできる。REST APIキーは作成後に編集できないことに注意せよ。

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

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

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

REST APIキーのセキュリティ

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

REST API キーによって潜在的に機密性の高い REST API エンドポイントへのアクセスが許可される場合は、これらのキーをセキュリティで保護し、信頼できるパートナーとのみ共有します。これらのキーは一般公開しないでください。例えば、このキーを使ってウェブサイトからAJAXコールを行ったり、その他の一般的な方法で公開してはいけません。

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

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

API IP の許可リスト

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

何も指定しない場合、すべての 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 クライアントライブラリは、ユーザーエンドポイントをサポートしています。