バルクAPI

バルクAPIは、大量のユーザー・データをOracle Data Cloudプラットフォームにプログラマティックにオンボーディングします。これにより、ユーザー・データAPIへの多くのコールを1つのHTTPS POSTの本文でバッチ処理できます。バルクAPIを使用すると、大量の個々のコールをユーザー・データAPIに対して実行する場合と比較して、レイテンシが短縮され、スループットが最大化されます。バルクAPIを介して送信されたユーザー・データは、一般的には24時間以内にオンボーディングされます。

ノート: ユーザーがOracle Data CloudプラットフォームUIでキャンペーンを作成することはなくなりました。キャンペーン・ワークフローは、オーディエンス・ワークフローの一部になりました。ただし、プラットフォームでは引き続きキャンペーンを使用して、オーディエンス・データ配信を管理できます。キャンペーンは、UIユーザーがオーディエンスを配信する際に自動的に作成されます。APIでは、以前と同様にキャンペーンを作成して使用します。

前提条件

  • セットアップ: パートナ・シート用にバルクAPIをセットアップするには、My Oracle Support (MOS)に連絡してリクエストしてください。1日当たりのサブリクエストの最大数およびカスタム要件を指定してください。APIキーを提供する必要があります。
  • APIキー: Oracle Data Cloud Webサービスへのすべてのコールは、APIキーを使用して認証する必要があります。
  • ユーザー・データAPIコール: バルクAPIを使用するには、ユーザー・データAPIに慣れておく必要があります。
  • HTTPS: すべてのバルクAPIリクエストでHTTPSを使用する必要があります。Oracle Data Cloudプラットフォームでは、バルクAPIコールのHTTPはサポートされていません。

このトピックの内容  

サービスURI

https://bulkapi.bluekai.com/2/api

メッセージ署名

POSTリクエスト全体のメッセージ署名(bksig)を生成する必要があります。

リクエスト本文の個々のサブリクエスト(URIPath)ごとにAPI署名を生成する必要はありません。

bksigは、HMAC-SHA256署名アルゴリズムからの出力をBase64でエンコードした文字列です。

HMAC-SHA256(Secret key, POST_DATA)

POST_DATAは、リクエスト本文を参照します。

構文

https://bulkapi.bluekai.com/2/api?bksig=signature

例

https://bulkapi.bluekai.com/2/api?bksig=WFbm8mV+iFFimSXlbGb2YetEEsVe8n1IQTLUDVgQRpk%3D

ヘッダー

バルクAPIへのコールには、次のヘッダーを含める必要があります。

  • "ApiKey" : "APIKey"
  • "Accept" : "application/json"
  • "Content-Type" : "application/json"

リクエスト本文

バルクAPIリクエストのリクエスト本文は、次の例に示すように、Scatterオブジェクト内に一連のサブリクエストを含むJSON形式で表現されます。各サブリクエストは、基本的にはユーザー・データAPIコールです。

{
	"ResponseType": "Detail",
	"Method": "POST",
	"ResponseCallbackUrl": "https://example.com/uri",
	"Scatter": [{
		"Method": "POST",
		"URIPath": "/getdata/12345/v1.2?bkuid=bkUID&phint=filter%3DcampId1&idfa=IDFA",
		"RequestID": "123ABC"
	}, {
		"Method": "POST",
		"URIPath": "/getdata/12345/v1.2?bkuid=bkUID&phint=filter%3DcampId1&idfa=IDFA",
		"RequestID": "234BCD"
    },
    . . .
  ]
}

メイン・リクエストのリクエスト・プロパティ

プロパティ タイプ 説明
Method 文字列 GETやPOSTなど、サブリクエストのHTTP動詞を指定します
ResponseCallbackUrl 文字列 (推奨)レスポンスが処理後に送信される完全修飾URLを指定します。指定すると、元のバルクAPIリクエスト接続は、リクエストが受信された直後にクローズされます。

コールバック・サーバーURIが失敗した場合、バルクAPIはコールバックURL経由でレスポンスの送信を再試行しません。

重要: このプロパティを空またはnull値に設定した場合、レスポンスは、バルクAPIリクエストと同じ接続上でストリーミングされ、接続はすべてのサブリクエストが処理されるまで待機します。リクエストのサブリクエストが2,000個を超えると、レスポンスの待機中に接続リセット・エラーが発生する可能性があるため、これは本番ではお薦めしません。
ResponseType 文字列 バルクAPIリクエストに対するレスポンスの詳細レベルを指定します。
  • Detail: メイン・リクエストの最初の200レスポンスに加えて、各サブリクエストに対して送信される詳細なJSONレスポンス本文が含まれます。レスポンスは、対応するリクエストが完了すると使用可能になりますが、その順番は、送信された順番とは異なる場合があります。各サブリクエストにRequestIDが含まれている場合、これは対応するレスポンスに含まれます。
  • None: バルク・リクエスト全体に対して1つの200レスポンスが送信されます。サブリクエストに対して詳細は送信されません。
  • Summary: ステータス(200、404またはその他のHTTPコード)、リクエスト数およびすべてのサブリクエストのRequestIDのカンマ区切りリストが含まれます。
Scatter オブジェクト 一連のHTTPサブリクエストを記述するオブジェクト

サブリクエスト・プロパティ(Scatterの下)

プロパティ タイプ 説明
Method 文字列 GETやPOSTなど、サブリクエストのHTTP動詞を指定します
RequestID 文字列 (推奨)サブリクエストの一意の識別子で、トレーサビリティ、各サブリクエストとそのレスポンスの関連付け、各サブリクエストのステータスのトラッキングに使用されます。RequestID値にCookie IDを使用するか、別の一意の文字列を生成できます。

サブリクエストは送信されたときと必ずしも同じ順序では返されないため、RequestID値を指定すると、サブレスポンスを解析したり、それをサブリクエストと関連付けるために役立ちます。
URIPath 文字列 ユーザー・データAPIへのサブリクエストのコールのURLパス

 

{
	"BulkHost": "bulkapi.bluekai.com",
	"Gather": [{
		"RequestID": "123ABC",
		"Body": {
			"categories": [],
			"userid": "XYZ123",
			"msg": "ok",
			"status": 200
		}
	}, {
		"RequestID": "234BCD",
		"Body": {
			"categories": [],
			"userid": "ABC456",
			"msg": "ok",
			"status": 200
		}
	}, {
		"RequestID": "345CDE",
		"Body": {
			"status": 499
		}
	}]
}
{
	"BulkHost": "bulkapi.bluekai.com",
	"Gather": [{
		"Status": 200,
		"NumberOfRequests": 2,
		"RequestIDs": ["1461841582583", "1461841582100"]
	}, {
		"Status": 404,
		"NumberOfRequests": 1,
		"RequestIDs": ["1461841582873"]
	}, {
		"Status": 499,
		"NumberOfRequests": 1,
		"RequestIDs": ["1461841582190"]
	}]
}
{
	"BulkHost": "bulkapi.bluekai.com",
	"Gather": []
}

制限

  • バッチPOSTリクエストの最大サイズは100 MBです。
  • バッチ・コール当たりのサブリクエストの最大数は、500,000です。

同じユーザーに対する複数のコール。同じユーザーに対して複数のユーザー・データAPIコールを渡す場合は、バッチ・ファイル内でコールが連続して実行されないように分離するか、1つのコールに統合します。同じユーザーに対してコールを連続して実行すると、競合状態となり、1つ以上のコールがユーザーのプロファイルにデータを追加できなくなる可能性があります。

レスポンス・コード

メインのバルクAPIリクエストに問題がある場合、レスポンスでは次のいずれかが使用されます。

コード メッセージ
400 Bad Request: invalid API key, invalid JSON, or the request does not contain required properties
401 Unauthorized (invalid signature or no signature present)
402 Payment Required (daily limit exceeded)
403 Forbidden (number of subrequests does not meet "minimum sub-requests per batch")
404 Not Found
405 Method Not Allowed (invalid request: invalid HTTP method)
411 Length Required (post request body has 0 size)
413 Payload Too Large (maximum number of subrequests exceeded)
500 Internal Server Error: This can indicate standard error or that something wrong with bulk service, such as a POST larger than 100 MB.

ノート: これらのレスポンス・コードは、メインのバルクAPIリクエスト用です。デフォルトでは、プラットフォームはサブリクエストを最大3回試行しますが、失敗したコールをログに記録しません。各サブリクエストのステータスは、対応するサブレスポンスを確認することで把握できます(ResponseTypeプロパティがDetailまたはSummaryに設定されている場合)。最終ステータス・コード200または404は、レスポンス本文のStatus値でサブリクエストごとに報告されます。特殊なバルク収集ステータス・コード499は、空白文字が含まれていたり、先頭が/getdata/でないURIPath値など、無効なサブリクエストURIを示します。
サブリクエスト・エラーの詳細は、ユーザー・データAPIのエラー・レスポンスを参照してください。

SLA 

バルクAPIを介して送信されたユーザー・データは、一般的には24時間以内にオンボーディングされます。

このAPIの詳細は、My Oracle Support (MOS)にお問い合せください。

さらに学ぶ

ユーザー・データAPI

認証