Data Cloud リファレンスガイド
j取り込み API の使用開始
Data Cloud で API を使用する前に、前提条件を完了し、認証を設定し、一括取り込み API およびストリーミング取り込み API に適用される制限を把握します。
前提条件
- 取り込み API コネクタを設定する。データを消費するエンドポイントとペイロードを定義します。
- データストリームを作成およびリリースする。取り込みジョブを設定し、外部消費用の API を公開します。
- 接続アプリケーションを設定する。外部アプリケーションが OAuth を使用して Salesforce と統合できるようにします。
- Salesforce OAuth 認証フローから Data Cloud アクセストークンを要求します。API 要求の実行に必要なアクセストークンを取得および更新するための OAuth ダンスを実装します。
認証
Data Cloud 取り込み API は、他の Salesforce REST API でサポートされるすべての OAuth 2.0 フローをサポートする RESTful API のセットです。API を介してデータを読み込むには、接続アプリケーションに次の範囲が必要です。
- Data Cloud の取り込み API データのアクセスおよび管理 (cdp_ingest_api)。
- データへのアクセスと管理 (api)。
- ユーザーに代わっていつでも要求を実行 (refresh_token, offline_access)。
接続アプリケーションに適切な範囲が設定されたら、Salesforce にアクセストークンを要求し、Data Cloud アクセストークンと交換します。アクセストークンは、ベアラースキーマを使用した Authorization ヘッダーで送信されます。
レコードで有効な日付形式
取り込み API は、ISO 8601 UTC Zulu 形式をサポートしています。
- 日付値を指定するには yyyy-MM-dd 形式を使用します。たとえば、2021-07-05 です。
- yyyy は 4 桁の年号
- MM は 2 桁の月 (01 ～ 12)
- dd は 2 桁の日付 (01 ～ 31)
- dateTime 項目を指定するには、yyyy-MM-ddTHH:mm:ss.SSSZ 形式を使用します。例: 2021-07-05T09:31:44.457Z
- yyyy は 4 桁の年号
- MM は 2 桁の月 (01 ～ 12)
- dd は 2 桁の日付 (01 ～ 31)
- 「T」はこの後に時刻が記述されることを示す区切り文字
- HH は 2 桁の時間 (00 ～ 23)
- mm は 2 桁の分 (00 ～ 59)
- ss は 2 桁の秒 (00 ～ 59)
- SSS は省略可能な 3 桁のミリ秒 (000 ～ 999)
- 「Z」はタイムゾーンが UTC であることを示す
取り込み一括 API の制限
| 項目 | 説明 |
|---|---|
| API の使用制限 | 各要求の後、アプリケーションで応答コードを確認する必要があります。HTTP 429 Too Many Requests 状況コードは、アプリケーションの要求頻度を減らす必要があることを示しています。 |
| 一括ジョブの保持期間 | 状況が Open または Upload Complete で、経過日数が 7 日を超えている未完了の一括ジョブは取り込みキューから削除されます。 |
| ジョブあたりの最大ファイル数 | 一括ジョブごとに一度に 1 つのファイルをアップロードできます。1 つのジョブで最大 100 ファイルを保持できます。 |
| 最大ペイロードサイズ | Bulk API を介してアップロードされる CSV ファイルの最大サイズは 150 MB です。 |
| 1 時間あたりに許可される要求またはジョブの数 | 20 |
| 一度に許可される同時要求またはジョブの数 | 5 |
取り込みストリーミング API の制限
| 項目 | 説明 |
|---|---|
| API の使用制限 | 各要求の後、アプリケーションで応答コードを確認する必要があります。HTTP 429 Too Many Requests 状況コードは、アプリケーションの要求頻度を減らす必要があることを示しています。 |
| 予測される遅延 | データは約 3 分ごとに非同期で処理されます。 |
| 要求あたりの最大ペイロードサイズ | ストリーミング API を介してアップロードされる JSON データの最大ボディサイズは要求ごとに 200 KB です。 |
| 削除可能な最大レコード数 | 最大 200 件のレコードをストリーミング API によって削除できます。 |
| すべての取り込み API オブジェクトエンドポイントでの 1 秒あたりの合計要求数 | 250 要求 |
状況コードとエラー応答
| HTTP 応答コード | 説明 |
|---|---|
| 200 OK | 要求が正常に完了しました。 |
| 201 Created | リソースが正常に作成されたことを示します。 |
| 202 Accepted | 要求が受諾されました。データは非同期で処理されます。 |
| 204 No Content | ジョブが正常に削除されました。 |
| 400 Bad Request | クライアントエラーのためサーバーが要求を処理できません。原因として、不正な要求構文または無効なリクエストボディが考えられます。 |
| 401 Unauthorized | JWT が無効または期限切れのため、認証に失敗しました。トークンを更新してください。 |
| 404 Not Found | クライアントエラー: 要求されたリソースが存在しません。 |
| 409 Conflict | クライアントエラー: この状況ではジョブの状況を更新できません。 |
| 429 Conflict | 一定の時間内にユーザーが送信した要求数が多すぎます。バックオフポリシーを実装して要求数を減らしてください。 |
| 500 Internal Server Error | 内部サーバーエラー。要求を再試行してください。 |
データアップロードの制限
- ストリーミングの場合: 小さなペイロード (1 回の要求で 200 KB まで)
- 一括の場合: 最大 150 MB の大きな CSV