API ワークフロー

このガイドでは、Deal Sync API を使用して取引を作成、キャンセル、取得、更新、交渉するための一般的な API ワークフローについて説明します。

取引を作成する

  1. externalDealId フィルタを使用して LIST products を呼び出し、商品がすでに作成されているかどうかを確認します。フィルタ文字列では、camelCase の externalDealId と snake_case の external_deal_id の両方がサポートされています。external_deal_id はすべての商品で一意である必要があります。

    GET https://dv360seller.googleapis.com/v1beta1/{parent=exchanges/*/orders/*}/products?filter=externalDealId="{external_deal_id}"

  2. 注文 を作成します。 注文名はディスプレイ＆ビデオ 360 によって生成されます。この ID は、後で取得できるようにシステムに保存することをおすすめします。

  3. 注文 の下に商品を作成します。 商品名はディスプレイ＆ビデオ 360 によって生成されます。この ID は、後で取得できるようにシステムに保存することをおすすめします。

または、external_deal_id を使用して LIST を呼び出すこともできます。リソース名にはオーダー ID と商品 ID の両方が含まれているため、親注文を特定できます。

取引をキャンセルする

  1. 注文ステータスを CANCELEDに更新します。 キャンセルは、注文がまだ承認されていない場合にのみサポートされます。CANCELED は最終状態です。キャンセルした注文を再度有効にすることはできません。注文に商品が含まれている場合、その external_deal_id を再利用することはできません。

取引の詳細を取得する

  1. 注文 の詳細を取得します。 ユーザーが注文を承認、アーカイブ、キャンセルすると、ステータスが更新されます。
  2. 商品の 詳細を取得します。

取引のリストを取得する

  1. LIST ステータス フィルタを使用して orders を実行し、承認済みまたは承認待ちの 注文をすべて取得します。
  2. LIST products を external_deal_id フィルタを使用して実行します。
  3. 注文内のすべての商品を一覧表示します。

取引を更新する

  1. サイト運営者の連絡先情報の注文を更新します。
    1. name は更新できません（updateMask で設定できません）。API を使用してステータスを CANCELED に設定することのみが可能です。
    2. partner_id は更新できません。
  2. 特定の取引条件の更新について、商品を更新します。
    1. name、externalDealId、transactionType、pricingType、 updateTime は更新できません。
    2. displayName を更新する場合、ユーザーの再承認は必要ありません。
    3. rateDetails または creativeConfig を更新すると、親注文のステータスが PENDING_ACCEPTANCE に変わります。以前の注文がすでに承認されているかどうかに関係なく、ディスプレイ＆ビデオ 360 の広告主は [交渉] ページで新しい条件を承認するよう求められます。

ユーザーが取引を承認したかどうかを確認する

  1. 対応する注文名がわかっている場合は、 注文 を取得します。status フィールドを確認します。
  2. 注文名がトラッキングされていない場合は、external_deal_id フィルタを使用して商品を一覧表示し、 商品名 から注文名を特定して、 注文を 取得します。 status フィールドを確認します。

ユーザーが取引を設定しているかどうかを確認する（プログラマティック保証型取引のみ）

  1. 広告枠ソースを取得します。リソース名は exchanges/{exchangeId}/inventorysources/{external_deal_id} です。購入者のステータス を確認します。
    1. 予約取引:
      1. BUYER_STATUS_ACTIVE: 取引が承認され、設定されています。 ディスプレイ＆ビデオ 360 が取引条件に一致する入札リクエストを受け取ると、取引の費用が発生し始めます。取引の設定時に広告申込情報が自動的に生成されます。詳しくは、取引 の設定 をご覧ください。
      2. BUYER_STATUS_PENDING: 注文は承認されていますが、取引はまだ設定されていません。この状態では費用は発生しません。
      3. BUYER_STATUS_PAUSED: 広告主によって取引が一時停止されています。 この状態では費用は発生しません。
    2. 予約以外の取引:
      1. BUYER_STATUS_ACTIVE: 取引が承認されています。ディスプレイ＆ビデオ 360 が一致する入札リクエストを受け取り、有効な広告申込情報が取引をターゲットに設定し、入札リクエストが広告申込情報のターゲティング条件に一致すると、取引の費用が発生し始めます。詳しくは、Line Itemsをご覧ください。（注: 取引が広告申込情報によってターゲットに設定されているかどうかを照会する販売者 API はありません）。
      2. BUYER_STATUS_PENDING: 予約以外の取引には適用されません。
      3. BUYER_STATUS_PAUSED: 広告主によって取引が明示的に一時停止されています。この状態では費用は発生しません。

承認後に取引を一時停止または一時停止解除する

  1. 広告枠ソース の販売者のステータスを更新します。
    1. 一時停止または一時停止解除しても、取引の配信は停止されません。販売者が取引を一時停止すると、ディスプレイ＆ビデオ 360 の UI に情報メッセージが表示され、費用が発生しない取引のトラブルシューティングに役立ちます。

再交渉（承認後に取引を更新する）

再交渉とは、購入者が取引を承認した後に取引に加えられた更新を指します。これにより、エクスチェンジと購入者は既存の取引の条件を調整できます。 たとえば、エクスチェンジが承認された 取引のフライト終了時間が正しくないことが判明した場合、エクスチェンジは Product Patch を使用して、取引の配信が開始される前にディスプレイ＆ビデオ 360 の購入者に更新を push できます。

許可される変更と許可されない変更

取引の交渉と再交渉のルールの詳細については、ディスプレイ＆ビデオ 360 ヘルプセンターの記事をご覧ください。

前へ
エンティティ構造
次へ
ベータ版プロセス