Digital Platform API - Batch Segment Service

Batch Segment Service を使用すると、バッチ/一括アップロード フレームワークを使用して、Xandr プラットフォームに対象ユーザーをアップロードできます。 このデータは、キャンペーンターゲティングや利回り管理の目的で、買い手または売り手からのデータと組み合わせて使用できます。 Batch Segment Service を介して送信されるすべてのデータは、既にシステム内の既存のセグメント データに追加されます。

以下の機能があります。

• 圧縮ファイルをアップロードする機能
• セグメント データのエラー チェック
• 構成可能な入力ファイル形式
• アップロードが成功したことを確認する
• 全体的な処理状態に関するフィードバック
• 場所に関係なく、ユーザーへのセグメントの関連付け
• 最大データ 量が多い

最適な結果を得るには、 Batch Segment Service のベスト プラクティスにベスト プラクティスを実装することを強くお勧めします。

処理用のセグメント ファイルを追加する

セグメント ファイルをシステムに追加するプロセスは 3 ステップです。 まず、ジョブ ID 番号とアップロード URL を要求します。 次に、割り当てられたアップロード URL にファイルをアップロードします。 3 番目に、ジョブの処理状態をチェックします。 現時点では、ファイルは個々の行の最大 1800 セグメントに制限されることに注意してください。 1 人のユーザーに対して 1800 を超えるセグメントがある場合は、その行を複数行に分割する必要があります。

• 手順 1. アップロード URL とジョブ ID を要求する
• 手順 2. アップロード URL にファイルを投稿する
• 手順 3. ジョブの状態を確認する

手順 1. アップロード URL とジョブ ID を要求する

アップロードされる各セグメント データ ファイルは、特定のジョブ ID に関連付けられている必要があります。 この ID は、アップロード URL を作成し、ファイルの処理状態を追跡するために使用されます。 最初の手順は、空 POST の要求をサービスに送信することです。

$ curl -b cookies -X POST "https://api.appnexus.com/batch-segment?member_id=456"

{
 "response": {
  "id": 123,
  "status": "OK",
  "batch_segment_upload_job": {
   "job_id": "JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549",
   "id": 123,
   "member_id": 456,
   "last_modified": "2012-05-21 16:42:29",
   "upload_url": "https://01.data-api.prod.adnxs.net/segment-upload/JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549"
  },
  "start_element": 0,
  "count": 1,
  "num_elements": 100,
  "dbg_info": {
  ...
  }
 }
}

手順 2. アップロード URL にファイルを投稿する

ファイルのアップロード URL は、 フィールドの手順 1 に対する JSON 応答で指定されます upload_url。 処理するには、この URL へのセグメント ファイルが必要 POST です。 アップロードが成功したかどうかを示す JSON オブジェクトを受け取ります。 アプリケーションでアップロード URL をハードコーディングしないでください。フィールドから upload_url 動的に取得してください。

$ curl -v -H 'Content-Type:application/octet-stream' -b cookies -X POST --data-binary @segment_file "https://01.data-api.prod.adnxs.net/segment-upload/JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549"

* About to connect() to 01.data-api.prod.adnxs.net port 80
*   Trying 64.210.62.71... connected
* Connected to 01.data-api.prod.adnxs.net (64.210.62.71) port 80
> POST /segment-upload/FkmOY7oL2Qy2aCE7NrhE1BHVoJA0wi1337697712 HTTP/1.1
> User-Agent: curl/7.15.5 (x86_64-redhat-linux-gnu) libcurl/7.15.5 OpenSSL/0.9.8b zlib/1.2.3 libidn/0.6.5
> Host: 01.data-api.prod.adnxs.net
> Accept: */*
> Content-type:application/octet-stream
> Content-Length: 116
>
> 7652266028043224430;5848:0,5849:1440,5850:14404013681496264948522;5013:0,5014:15508802117132500293405;5851:0,5847:-1HTTP/1.1 200 OK
< Date: Tue, 22 May 2012 14:48:02 GMT
< Content-Type: application/json
< Transfer-Encoding: chunked
< Server: Jetty(7.6.2.v20120308)
* Connection #0 to host 01.data-api.prod.adnxs.net left intact
* Closing connection #0
{"response":{"segment_upload":{"job_id":"FkmOY7oL2Qy2aCE7NrhE1BHVoJA0wi1337697712"},"status":"OK"}}

SSL アップロード URL の例

curl -b cookie -c cookie -X POST -s -d '' "https://api.appnexus.com/batch-segment?member_id=958"

"batch_segment_upload_job": {
      "id": 14841671,
      "job_id": "qGQhSZ1qvd2hSsJ9svTz32qgxq7z5b1439315424",
      "member_id": 958,
      "last_modified": "2015-08-11 17:50:24",
      "upload_url": "https://data-api-gslb.adnxs.net/segment-upload/qGQhSZ1qvd2hSsJ9svTz32qgxq7z5b1439315424"
    }

手順 3. ジョブの状態を確認する

最後に、要求を送信して処理状態をGETチェックします。 JSON 応答には、ファイルの処理にかかった時間やエラーの数 (ある場合) などの情報が含まれます。 などの結果フィールドを確認する前に、 num_validまでphase="completed"待つ必要があることに注意してください。 詳細については、以下の 「JSON フィールド 」を参照してください。

$ curl -b cookies "https://api.appnexus.com/batch-segment?member_id=456&job_id=JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549"

{
 "response": {
  "start_element": 0,
  "count": 1,
  "batch_segment_upload_job": {
   "phase": "completed",
   "start_time": "2012-05-21 20:04:35",
   "uploaded_time": "2012-05-21 20:04:41",
   "validated_time": "2012-05-21 20:07:24",
   "completed_time": "2012-05-21 20:08:24",
   "error_code": null,
   "time_to_process": "2.69",
   "percent_complete": 100,
   "num_valid": 200000,
   "num_valid_user":100000
   "num_invalid_format": 0,
   "num_invalid_user": 0,
   "num_invalid_segment": 0,
   "num_unauth_segment": 1,
   "num_past_expiration": 0,
   "num_inactive_segment": 0,
   "num_other_error": 0,
   "error_log_lines": " \n\nnum_unauth_segment-4013681496264948522;5013:0,5014:1550",
   "segment_log_lines": "\n5010:100000\n5011:50000\n5012:50000",
   "id": 88,
   "job_id": "4tGhzv2PojNGQpq0MYaoaOa70cuF061337630675",
   "member_id": 456,
   "created_on": "2012-05-21 20:04:35",
   "last_modified": "2012-05-21 20:08:24"
  },
  "dbg_info": {
  ...
  },
  "status": "OK",
  "num_elements": 100
 }
}

アップロード エラーの可能性

0.5 GB を超えるファイルをアップロードしようとしています

{"response":{"status":"ERROR","error_code":"FILESIZE_LIMIT_EXCEEDED","errors":["Member exceeds maximum byte size allowed for a file"]}}

バッチ セグメントアップロード ジョブのエラー コード

""batch_segment_upload_job": {
      "phase": "error",
      "start_time": "2015-08-13 18:40:32",
      "uploaded_time": null,
      "validated_time": null,
      "completed_time": null,
      "error_code": "uploading-error",
      "time_to_process": "0.00",
      "percent_complete": 0,
      "num_valid": 0,
      "num_invalid_format": 0,
      "num_valid_user": 0,
      "num_invalid_user": 0,
      "num_invalid_segment": 0,
      "num_invalid_timestamp": 0,
      "num_unauth_segment": 0,
      "num_past_expiration": 0,
      "num_inactive_segment": 0,
      "num_other_error": 0,
      "error_log_lines": null,
      "segment_log_lines": null,
      "id": 11661553,
      "job_id": "Pm3oCUf5CSVKIOt4mAqOzdt6K3qInj1431542432",
      "member_id": 958,
      "created_on": "2015-05-13 18:40:32",
      "last_modified": "2015-05-13 18:40:33"
    }

次に示すエラーは、次の場合に発生する可能性があります。

• アップロードを取り消しました。
• アップロード フェーズが 90 分を超えています。
• 4 つのアップロード制限 (日単位のバイト数、時間単位のバイト数、または時間単位の行の制限) のいずれかに達しました。

1 日あたりのバイト アップロード制限を超えようとしている

 {"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member exceeds maximum allowed bytes per day"]}}

1 時間あたりのバイトアップロード制限を超えようとしている

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member exceeds maximum allowed number of lines per hour"]}}

1 日あたりのアップロード制限を超えようとしている

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member exceeds maximum allowed number of lines per day"]}} 

1 時間あたりのアップロード制限を超えようとしている

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member exceeds maximum allowed lines per hour"]}}

アップロードまでの最大時間を超える

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Maximum upload time exceeded"]}}

発生する可能性のある処理エラー

無効な形式

フィールドの値が num_invalid_format より"0"大きい場合は、フィールド内error_log_linesの値をチェックします。

次の例では、フィールドには num_invalid_format の値 "1"が表示され、フィールドに詳細が error_log_lines 指定されています。

フィールドで、次の手順を error_log_lines 実行します。

• num_invalid_format は、アップロードされたファイル内の行の解析に問題が発生したことを示します。
• "failed with an illegal number of fields" は、ブロック内 segment_fields のフィールドの数が、バッチ セグメント構成で定義されたものと一致しなかったことを示します。詳細については、「 Batch Segment Service - Configuration」を参照してください。

この場合、構成では、ブロックSEG_IDVALUEEXPIRATION内で 3 つのフィールドが定義されることを想定していますが、パーサーで見つかったフィールド SEG_IDVALUEは 2 つだけで、エラーが表示されます。

num_invalid_format と error_log_lines の例

"batch_segment_upload_job": {
phase": "completed",
"error_code": null,
"time_to_process": "0.01",
"percent_complete": 100,
"num_valid": 0,
"num_invalid_format": 1,
"num_valid_user": 0,
"num_invalid_user": 0,
"num_invalid_segment": 0,
"num_invalid_timestamp": 0,
"num_unauth_segment": 0,
"num_past_expiration": 0,
"num_inactive_segment": 0,
"num_other_error": 0,
"error_log_lines": "num_invalid_format-WINDOWSADID-USER-ID;SEG_ID:VALUE~9 failed with an illegal number of fields",
"segment_log_lines": null,
"start_time": "2015-08-13 18:40:32",
"uploaded_time": "2015-08-13 18:42:32",
"validated_time": "2015-08-13 18:42:32",
"completed_time": "2015-08-13 18:42:33",
"id": 123412341234,
"job_id": "Pm3oCUf5CSVKIOt4mAqOzdt6K3qInj1431542432",
"member_id": 958,
"created_on": "2015-08-13 18:40:32",
"last_modified": "2015-08-13 18:42:33"
}

ファイルのアップロード履歴を表示する

過去 30 日以内のすべてのセグメント ファイルのアップロードに関するメタデータを表示するには、 GET クエリ文字列で指定した を member_id 使用してサービスを呼び出します。 JSON 応答には、オブジェクトの配列が batch_segment_upload_job 含まれます。 オブジェクトの特定のフィールドの詳細については、以下のbatch_segment_upload_job「JSON フィールド」を参照してください。

m$ curl -b cookies 'https://api.appnexus.com/batch-segment?member_id=456'

{
   "response" : {
      "batch_segment_upload_job" : [
         {
           "phase": "completed",
            "start_time": "2012-05-22 16:48:55",
            "uploaded_time": "2012-05-22 16:48:56",
            "validated_time": "2012-05-22 16:49:01",
            "completed_time": "2012-05-22 16:49:01",
            "error_code": null,
            "time_to_process": "0.04",
            "percent_complete": 100,
            "num_valid": 0,
            "num_invalid_format": 0,
            "num_invalid_user": 2,
            "num_invalid_segment": 0,
            "num_unauth_segment": 1,
            "num_past_expiration": 0,
            "num_inactive_segment": 0,
            "num_other_error": 0,
            "error_log_lines": " \n\nnum_unauth_segment-4013681496264948522;5013:0,5014:1550\nnum_invalid_user-7652266028043224430;5848:0,5849:1440,5850:1440\nnum_invalid_user-8802117132500293405;5851:0,5847:-1",
            "id": 98,
            "job_id": "T1v98eIOlCZndeLGSXD0nrs57L8ES11337705335",
            "member_id": 456,
            "created_on": "2012-05-22 16:48:55",
            "last_modified": "2012-05-22 16:49:01"
         },
     ...
    }
  }
}

REST API

JSON フィールド

バッチ セグメントのアップロード ジョブ

処理ジョブの状態を要求すると、オブジェクトが返 batch_segment_upload_job されます (データ プロバイダーの場合、これは 1 つのオブジェクトを含む配列になります)。 サービスに対して行う要求に応じて、次のメタデータの一部またはすべてが含まれます。 要求の必要なシーケンスの詳細については、以下の 「処理用のセグメント ファイルの追加 」セクションを参照してください。

関連トピック

Batch Segment Service - ファイル形式