次の方法で共有

Geo Polygon Segment サービス

  • [アーティクル]

注:

このサービスは Alpha にあります。 この機能は予告なく変更される場合があり、クライアントを選択する場合にのみ使用できます。 アルファ テストに参加する場合は、アカウント マネージャーにお問い合わせください。

Geo Polygon Segment Service を使用すると、geo ポリゴン セグメントを作成、構成、およびエクスポートできます。 geo ポリゴン セグメントは、既知のテキスト (WKT) ポリゴン座標で指定されたユーザーの場所の一覧です。 既知のテキスト (WKT) は、座標を使用してマップ上のベクター ジオメトリ オブジェクトを表すテキスト マークアップ言語です。 geo ポリゴン セグメントを作成した後、自動的に関連付けられたセグメントを使用して、複数のユーザーの場所の地理的なターゲット設定を行うことができます。 Geo Polygon Segment Service を使用すると、geo ポリゴン WKT の CSV ファイルを geo セグメントにアップロードできます。 広告申込情報レベルでターゲット設定を行うには、同じ geo セグメントを使用できます。

警告

Geo Polygon Segment Service は、既知のテキスト (WKT) ポリゴン座標に基づいています。 これは、地理ポリゴンを 緯度と経度 (緯度、長) 形式ではなく経度と緯度 (緯度、緯度) 形式でアップロードする必要があることを示します。

プロセス フロー

geo ポリゴンを含むセグメントを作成するには、次の手順に従います。

  1. シェル セグメントを作成します。 シェル セグメントを作成するには、 /geo-polygon-segment エンドポイントへの POST 呼び出しを行います。
  2. シェル セグメントにポリゴンをアップロードします。 ポリゴンを含む CSV ファイルを作成し、 /geo-polygon-segment/{segmentID}/upload-polygon エンドポイントへの POST 呼び出しを行うことができます。
  3. アップロードが成功したかどうかを確認するには、多角形のアップロード要求を送信した後、 /geo-segment-processor/job-status エンドポイントを介してジョブの状態を確認します。

REST API

HTTP メソッド エンドポイント 説明
POST https://api.appnexus.com/geo-polygon-segment

(new-geo-polygon-segment JSON)		 新しい geo ポリゴン セグメントを作成する
POST https://api.appnexus.com/geo-polygon-segment/{segmentID}/upload-polygon

(add-polygons.csv)		 セグメントにポリゴンを追加する
POST https://api.appnexus.com/geo-polygon-segment

(new-geo-polygon-segment JSON)		 新しい geo ポリゴン セグメントを作成する
POST https://api.appnexus.com/geo-polygon-segment/select

POST -d '{"criteria":{},"ordering": {"direction":"desc","by":"id"}}' "https://api.appnexus.com/geo- polygon-segment/select"		 メンバーのすべての geo ポリゴン セグメントを表示する
POST https://api.appnexus.com/geo-polygon-segment/{segmentID}/polygon/select

POST -d '{"criteria":{},"ordering":{"direction":"desc","by":"id"}}' "https://api.appnexus.com/geo-polygon-segment/{segmentID}/polygon/select"		 特定の geo ポリゴン セグメントの詳細を表示する
POST https://api.appnexus.com/geo-polygon-segment/{segmentID}/polygon/select

POST -d '{"criteria":{},"ordering":{"direction":"desc","by":"id"}}' "https://api.appnexus.com/geo-polygon-segment/{segmentID}/polygon/select"		 セグメント内のすべての geo ポリゴン定義を表示する
GET https://api.appnexus.com/apd-status 最近のアップロードを表示する
GET https://api.appnexus.com/apd-status?id=%7Bapd_id%7D 特定のアップロードの状態を表示する
GET https://api.appnexus.com/geo-segment-processor/job-status geo ポリゴンアップロードの状態を表示する
DELETE https://api.appnexus.com/geo-polygon-segment/{segmentID} geo ポリゴン セグメントを削除する
DELETE https://api.appnexus.com/geo-polygon-segment/%7BsegmentID%7D/polygon/delete

POST -d '{"criteria":{"id":{"in":[_polygon_feature_id_]}}}' "https://api.appnexus.com/geo-polygon-segment/{segmentID}/polygon/delete"		 geo ポリゴン セグメントから特定のフィーチャを削除する

JSON フィールド

新しい geo ポリゴン セグメント JSON を作成する

フィールド 種類 説明
code string geo ポリゴン セグメントを呼び出すためのユーザー定義コード。 たとえば、"GEO123" のように指定します。
description string この geo ポリゴン セグメントの説明
short_name string geo ポリゴン セグメントの説明に使用される短い名前

必須:POST
regional_centers オブジェクトの配列 geo ポリゴン セグメントが使用可能なリージョンの ID またはコード。
使用可能な値:
- ID: 1、2、または 3
- コード: "americas"、"emea"、"apac"

CSV ファイル形式

CSV ファイルの列名は Polygon と Name で、定義された geo ポリゴンの値が保持されます。

注:

列名は大文字と小文字が区別され、スペースはありません。 CSV ファイルで列名を指定する必要があります。

例

add-polygons.csv
Polygon,Name
"POLYGON((-73.79619781688602 40.926119268030504,-73.96923248485477 40.95931402310335,-74.09008209422977 
40.52648176879785,-73.23864166454227 
40.62870062738066,-73.38421051219852 40.926119268030504,-73.79619781688602 40.926119268030504))",FirstPolygon

注:

多角形は、CSV ファイル標準で必要に応じて引用符で囲む必要があります。

CSV ファイルを正常にアップロードすると、API は次のフィールドで応答を送信します。

  • geo_segment_polygon_id: Xandr のシステムに格納されている geo ポリゴンの自動生成 ID。
  • name: geo ポリゴンの名前。
  • apd_id: アップロードのジョブ ID。 アップロードの状態を追跡する場合は、これを追跡する必要があります。

注:

トラブルシューティングに必要なので、アップロード応答の記録を保持する必要があります。

例

新しい geo ポリゴン セグメントを作成する

$ cat new-geo-polygon-segment.json

{
  "short_name": "New Geo Polygon Segment",
  "description": "Creating a new geo polygon segment example",
  "regional_centers": [
    {
      "id": 1
    }
  ]
}

Alternatively

$ cat new-geo-polygon-segment.json
{
  "short_name": "New Geo Polygon Segment",
  "description": "Creating a new geo polygon segment example",
  "regional_centers": [
    {
      "code": "emea"
    }
  ]
}

$ curl -b cookies -d @new-geo-segment.json -X POST "https://api.appnexus.com/geo-polygon-segment"
{
 "id": 35619,
 "segment_id": 27258480,
 "created_on": "2021-08-04 03:17:41",
 "updated_on": "2021-08-04 03:17:41"
}

サポートされているすべてのリージョン センターを表示する

$ curl -b cookies "https://api.appnexus.com/regional-center"
{
 "regional_centers": [
   {
     "id": 1,
     "code": "emea",
     "name": "Europe, Middle East, Africa"
   },
  {
     "id": 2,
     "code": "americas",
     "name": "North, Central and South America"
  },
  {
     "id": 3,
     "code": "apac",
     "name": "Asia and Pacific"
  }
 ]
}

新しく作成されたセグメントにポリゴンをアップロードする

エンドポイント

POST /geo-polygon-segment/<segment_id>/upload-polygon

パラメーター

フィールド 説明
segment_id (パス内) セグメントの ID。

例

要求

POST https://api.appnexus.com/geo-polygon-segment/36039750/upload-polygon

Body

多角形を含む CSV ファイル。

Response

{
    "objects": {
        "polygons": [
            {
                "id": 54684042,
                "name": "FirstPolygon"
            },
            {
                "id": 54684043,
                "name": "SecondPolygon"
            }
        ],
        "apd_ids": {
            "americas": "b5fa59ea-a9a7-11ee-8c12-3cfdfed1a940"
        }
    },
    "job_id": 268,
    "segment_id": 36039750,
    "workflow": "UPLOAD_GEO_SEGMENT_POLYGON",
    "offset": 1, 
    "total": 2, 
  }

メンバーのすべての geo ポリゴン セグメントを表示する


$ curl -b cookies -c cookies -X POST -d '{"criteria":{},"ordering":{"direction":"desc","by":"id"}}'
"<https://api.appnexus.com/geo-polygon-segment/select>"

セグメント内のすべての geo ポリゴン定義を表示する


 curl -b cookies -c cookies -X POST -d '{"criteria":{},"ordering":{"direction":"desc","by":"id"}}'
 "<https://api.appnexus.com/geo-polygon-segment/27258480/polygon/select>"

最近のアップロードを表示する


curl -b cookies "<https://api.appnexus.com/apd-status>"

特定のアップロードの状態を表示する


curl -b cookies "<https://api.appnexus.com/apd-status?id=4d362ab8-f94d-11eb-a5ee-3cfdfec8e950>"

geo ポリゴンアップロードのアップロード状態を表示する

  curl -b cookies -c cookies -X GET "<https://api.appnexus.com/geo-segment-processor/job-status?geoSegmentId=86831>"

geo ポリゴン セグメントを削除する

エンドポイント

DELETE /geo-polygon-segment/<segment_id>

パラメーター

フィールド 説明
segment_id (パス内) セグメントの ID。

例

要求

DELETE https://api.appnexus.com/geo-polygon-segment/36039750

Response


{ 
    "job_id": 332, 
    "apd_ids": { 
        "americas": "98acb9c8-aa4b-11ee-b336-40a6b7543210" 
    }, 
    "segment_id": 36039750, 
    "workflow": "DELETE_GEOPOLYGON_SEGMENT" 
}

geo ポリゴン セグメントから特定のフィーチャを削除する

エンドポイント

POST /geo-polygon-segment/<segment_id>/polygon/delete

パラメーター

フィールド 説明
segment_id (パス内) ポリゴンを削除するセグメントの ID。

例

要求

POST https://api.appnexus.com/geo-polygon-segment/36039750/polygon/delete

Body

JSON


{
    "criteria": {
        "id": {
            "in": [54684042]
        }
    }
}

Response

JSON


{
    "job_id": 329,
    "segment_id": 36039750,
    "objects": {
        "polygons": [
            {
                "name": "FirstPolygon",
                "id": 54684042,
                "polygon_wkt": "POLYGON((-73.796197816886 40.9261192680305,-73.9692324848548 40.9593140231034,-74.0900820942298 40.5264817687979,-73.2386416645423 40.6287006273807,-73.3842105121985 40.9261192680305,-73.796197816886 40.9261192680305))"
            }
        ],
        "apd_ids": {
            "americas": "b5fa59ea-a9a7-11ee-8c12-3cfdfed1a940"
        }
    },
    "workflow": "DELETE_GEO_SEGMENT_POLYGON"
}

ジョブの状態を確認する

ジョブの状態を確認するには、応答で指定されたjob_idを使用して、ジョブ状態エンドポイントに要求を行います。

エンドポイント

GET /geo-segment-processor/job-status

パラメーター

フィールド 説明
jobId ジョブの ID。
geoSegmentId geo セグメント ID。
segmentId セグメント ID。
numJobsToRetrieve 取得するジョブの数。

アップロード要求または削除要求の進行状況を監視するには、特定のパラメーターを使用してジョブの状態を照会できます。

フィールド 種類 説明
job_state string ジョブ全体の現在の状態を示します。 ジョブ状態の使用可能な値は次のとおりです。
- created - ジョブはスケジュールされていますが、まだ実行されていません。
active - ジョブ全体に関連するジョブが現在処理中です。
取り消し - ジョブが手動で取り消されたか、エラーが原因で取り消されました。
retry - 内部要求が失敗した場合、ジョブは 1 回再試行される可能性があります。
完了 - ジョブが正常に完了しました。
期限切れ - ジョブは 12 時間後に処理のために選択されていないため、有効期限が切れており、処理されません。
failed - ある時点でエラーが発生し、ジョブが失敗しました。
進行中 - ジョブ全体が処理され、サブジョブがスケジュールされ、ジョブ キュー ジョブが完了する前に APD ジョブが完了することを継続的に確認するために処理されます。
job_id 番号 ジョブ全体の ID。
workflow 文字列 ジョブに関連付けられているワークフロー。 ジョブには、次のワークフローが関連付けられています。
- DELETE_GEOPOLYGON_SEGMENT
- DELETE_GEO_SEGMENT
- UPLOAD_GEO_SEGMENT_POLYGON
- DELETE_GEO_SEGMENT_POLYGON
- CREATE_GEO_SEGMENT_FEATURE
- DELETE_GEO_SEGMENT_FEATURE
geo_segment_id 番号 要求に関連付けられている geo セグメント ID。
注: 通常、内部 ID。ただし、この ID は地理的半径関連の要求に使用されます。
segment_id 文字列 要求に関連付けられているセグメント ID。
注: この ID は、geo ポリゴン関連の要求に使用されます。
job_results object ジョブに関する情報を含むオブジェクト。ジョブの処理が開始されると更新されます。
apdJobStatus - ジョブ ID によって APD ジョブの現在の結果が格納されます。
apdJobIds - リージョンごとのジョブ ID が含まれます。
initialJobRecordId - ジョブの ID。 これは、この要求で指定された jobId パラメーターと一致する必要があります。
jobCount - ジョブ全体を構成するサブジョブの数。
jobErrors - ジョブが失敗した理由、取り消された理由、または再試行された理由に関連するエラーが含まれます。
job_name string ジョブ キューの名前を指定します。 次の 2 つのジョブの種類があります。
- apd status check
- apd job complete.
また、要求の送信元の環境 (開発、ステージング、または運用環境) も示します。
- bff_apd_status_check_queue_<env>
- bff_apd_job_complete_queue_<env>
注: <env> は、 dev、 staging、または prodできます。
created_on string ジョブが作成された日付/時刻。
num_records 番号 ジョブに関連付けられているポリゴンまたはフィーチャの数。
たとえば、500 個のポリゴンをアップロードするように要求した場合、num_recordsは 500 になります。

Response


{
    "jobs":
    [
        {
            "job_state": "completed",
            "job_id": 270,
            "workflow": "DELETE_GEOPOLYGON_SEGMENT",
            "geo_segment_id": 36039750,
            "segment_id": 36039750,
            "job_results": {
                "jobCount": 1
            },
            "job_name": "bff_apd_status_check_queue_prod",
            "created_on": "2024-01-02 04:37:19",
            "num_records": 1
        }
    ]
}

注意すべき重要なポイント

  • Geo Polygon Segment Service は現在、穴を持つ geo ポリゴン定義を受け入れていません (ジオメトリでは、穴を持つポリゴンは、1 つの外部境界と 1 つ以上の内部境界を持つエリアに接続された平面ポリゴンです)。 ポリゴン定義に穴が含まれている場合、サービスは穴を無視します。
  • セグメントでホストできるポリゴン定義の最大数は 50,000 です。
  • CSV ファイルのアップロードが成功すると、サービスは応答として apd_id と geo_segment_polygon_id を返します。 後でトラブルシューティングを行うには、それらを保存する必要があります。
  • アップロードされたファイルに無効な書式設定、引用符の欠落、末尾のスペース、セグメントに既に 50000 個のポリゴン定義があるなどの問題がある場合、応答に geo_segment_polygon_id はありません。 アップロード応答に apd_idのみが含まれている場合は、上記のいずれかの理由によりファイルが拒否されたことを示します。 このような場合は、問題を修正してアップロードを再試行することをお勧めします。
  • マルチポリゴンは現在サポートされていません。 複数のポリゴン定義を一意の個別のポリゴン定義に分割し、それらをアップロードしてください。
  • geo ポリゴン セグメントは、最大 1 つのリージョン センターに接続できます。