プロファイルインポートAPI

認証

すべてのプロファイルインポートAPIリクエストは、Authorizationヘッダーに静的APIキーが必要です:

Authorization: ApiKey

APIキーを作成するには、「 APIキーを作成する」をご覧ください。

ベースURL

ベースURLを見つけるには、SitecoreAIを開き、パフォーマンス>設定>プロファイルインポート>認証情報をクリックしてください。APIリクエストの**{base_url}としてAPIエンドポイント**値を使います。すべてのリクエストはパターン{base_url}/v1/batches/...に従っています。

エンドポイント

方法

経路

概要

POST

/v1/batches

プロファイルバッチファイルをアップロードします。

GET

/v1/batches/{batchId}/status

バッチの状況を確認してください。

GET

/v1/batches/{batchId}/stats

完了したバッチの詳細な統計情報を取得しましょう。

GET

/v1/batches/{batchId}/results

完了したバッチの結果ファイルをダウンロードしてください。

GET

/v1/batches

環境ごとにすべてのバッチをリストアップしてください。

プロファイルバッチファイルをアップロードします

プロファイルレコードを含むJSONLファイルをアップロードして処理します。

エンドポイント: POST /v1/batches

コンテンツタイプ: multipart/form-data

形状部品:

パート

種類

必須

概要

file

バイナリ

はい

処理するJSONLファイル。最大100MB。

md5

ストリング

はい

ファイルのMD5チェックサムは32文字の16進文字列として使われます。サーバーは自社のMD5を計算し、値が一致しなければアップロードを拒否します。詳細は「 JSONLファイルのMD5チェックサムを計算する」を参照してください。

例示リクエスト:

curl -X POST "{base_url}/v1/batches" \ -H "Authorization: ApiKey " \ -F "[email protected]" \ -F "md5=01556b1dcc2b3cb87889838ee349357a"

成功回答: 202 Accepted

{ "batchId": "7266232b-a7d4-496c-b0b3-be8dbde7495a", "status": "QUEUED", "checksumMd5": "01556b1dcc2b3cb87889838ee349357a", "fileSizeBytes": 1873, "createdAt": "2026-07-02T13:14

!注APIはHTTP 202 Acceptedを返しますが、201 Createdではありません。バッチは処理待ちに入っており、まだ処理されていません。

エラー応答:

現状

原因

400 Bad Request

無効な md5 形式、MD5チェックサムの不一致、空のファイル、またはマッピング仕様が10,000文字を超える場合。

401 Unauthorized

APIキーが欠落または無効です。

403 Forbidden

APIキーはバッチファイルのアップロード権限はありません。

429 Too Many Requests

キューの上限に達しました。この環境のためにすでにバッチがキューに入れられているか実行中です。

バッチ状況を確認してください

バッチの現在の状況を返します。

エンドポイント: GET /v1/batches/{batchId}/status

例示リクエスト:

curl "{base_url}/v1/batches/{batchId}/status" \ -H "Authorization: ApiKey "

回答:

{ "batchId": "7266232b-a7d4-496c-b0b3-be8dbde7495a", "status": "COMPLETED_WITH_ERRORS", "totalRecords": 12, "succeededRecords": 6, "failedRecords": 6, "processingTimeSeconds": 64, "startedProcessingAt": "2026-07-02T13:14

statusフィールドは、QUEUED、RUNNING、COMPLETED、COMPLETED_WITH_ERRORS、またはFAILEDのいずれかの値を持ちます。各状態の説明についてはバッチ状態を参照してください。

エラー応答:

現状

原因

401 Unauthorized

APIキーが欠落または無効です。

403 Forbidden

APIキーはこの操作を行う権限を持っていません。

404 Not Found

バッチは見つかりません。

バッチ統計の取得

バッチの詳細な統計情報(レコード数やエラー内訳を含む)を返します。バッチが最終状態(COMPLETED、COMPLETED_WITH_ERRORS、またはFAILED)に達した後に統計が利用可能です。

エンドポイント: GET /v1/batches/{batchId}/stats

例示リクエスト:

curl "{base_url}/v1/batches/{batchId}/stats" \ -H "Authorization: ApiKey "

回答:

{ "batchId": "7266232b-a7d4-496c-b0b3-be8dbde7495a", "status": "COMPLETED_WITH_ERRORS", "checksumMd5": "01556b1dcc2b3cb87889838ee349357a", "fileSizeBytes": 1873, "totalRecords": 12, "succeededRecords": 6, "createdRecords": 3, "updatedRecords": 3, "failedRecords": 6, "failedByCode": { "INVALID_RECORD": { "count": 6, "firstRecordIndex": 6, "firstDescription": "No identifier with a valid id and a recognised provider" } }, "processingTimeSeconds": 64, "createdBy": "[email protected]", "createdAt": "2026-07-02T13:14

応答フィールド:

フィールド

概要

batchId

バッチの一意識別子です。

status

現在のバッチの状況。

checksumMd5

アップロードされたファイルのMD5チェックサムです。

fileSizeBytes

アップロードされたファイルのサイズ(バイト単位)です。

totalRecords

入力ファイル内のレコードの総数。

succeededRecords

処理された記録数。

createdRecords

新規作成されたプロフィールの数。

updatedRecords

既存プロフィールの数を更新しました。

failedRecords

処理に失敗したレコードの数。

failedByCode

エラーコードごとの故障内訳、カウント、最初の故障記録インデックス、説明付き。

processingTimeSeconds

総処理時間は数秒です。

createdBy

バッチをアップロードしたユーザーです。

createdAt

バッチがアップロードされたときのことです。

startedProcessingAt

処理が始まった時。

finishedProcessingAt

処理完了時。

エラー応答:

現状

原因

401 Unauthorized

APIキーが欠落または無効です。

403 Forbidden

APIキーはこの操作を行う権限を持っていません。

404 Not Found

バッチは見つかりません。

結果をダウンロード

完了したバッチの結果ファイルをダウンロードします。ファイルはJSONL形式で、入力レコードごとに1行ずつ構成されています。各行にはレコードの結果が含まれ、成功したレコードの場合は解決済みプロファイルIDが記載されます。失敗した記録にはエラーコードや記述が含まれます。

出力フォーマットについては 、出力ファイル形式を参照してください。エラーコードの説明については「 レコードレベルのエラーコード」を参照してください。

エンドポイント: GET /v1/batches/{batchId}/results

例示リクエスト:

curl "{base_url}/v1/batches/{batchId}/results" \ -H "Authorization: ApiKey " \ -o results.jsonl

**回答:**200 OKJSONLファイルストリームを用いて。

エラー応答:

現状

原因

401 Unauthorized

APIキーが欠落または無効です。

403 Forbidden

APIキーはこの操作を行う権限を持っていません。

404 Not Found

バッチは最終状態に到達しておらず、結果ファイルも存在しません。

リストバッチ

環境ごとにすべてのバッチのページ付きリストを返します。

エンドポイント: GET /v1/batches

クエリパラメータ:

パラメータ

種類

デフォルト

概要

page

整数

1

ページ番号(1ベース)。

pageSize

整数

20

ページあたりのアイテム数。最大 100。

例示リクエスト:

curl "{base_url}/v1/batches?page=1&pageSize=10" \ -H "Authorization: ApiKey "

回答:

{ "items": { "batchId": "7266232b-a7d4-496c-b0b3-be8dbde7495a", "status": "COMPLETED_WITH_ERRORS", "totalRecords": 12, "succeededRecords": 6, "failedRecords": 6, "processingTimeSeconds": 64, "createdAt": "2026-07-02T13:14

応答フィールド:

フィールド

概要

items

バッチサマリーオブジェクトの配列。各項目は以下のフィールドで構成されています: batchId、 status、 totalRecords、 succeededRecords、 failedRecords、 processingTimeSeconds、 createdAt、 startedProcessingAt、 finishedProcessingAt。 FAILED ステータスのバッチでは、 totalRecords、 succeededRecords、 failedRecords フィールドは省略されます。

page

現在のページ番号(1ベース)。

pageSize

1ページあたり返品されるアイテム数。

totalItems

すべてのページにわたる環境のバッチ総数です。

エラー応答:

現状

原因

400 Bad Request

ページ番号パラメータが無効です。

401 Unauthorized

APIキーが欠落または無効です。

403 Forbidden

APIキーはこの操作を行う権限を持っていません。