Ad Manager SOAP API から移行する

Ad Manager SOAP API は、アドマネージャーのデータの読み取りと書き込み、レポートの実行を行うための従来の API です。移行できる場合は、Ad Manager API（ベータ版）を使用することをおすすめします。ただし、Ad Manager SOAP API のバージョンは、通常のライフサイクルでサポートされています。詳細については、Ad Manager SOAP API のサポート終了スケジュールをご覧ください。

次のガイドでは、Ad Manager SOAP API と Ad Manager API（ベータ版）の違いについて概説します。

学習

標準の Ad Manager SOAP API サービスメソッドには、Ad Manager API で同等のコンセプトがあります。Ad Manager API には、単一のエンティティを読み取るメソッドもあります。次の表に、Order メソッドのマッピング例を示します。

SOAP メソッド	REST メソッド
`getOrdersByStatement`	`networks.orders.get` `networks.orders.list`

認証

Ad Manager API（ベータ版）で認証するには、既存の Ad Manager SOAP API 認証情報を使用するか、新しい認証情報を作成します。どちらの方法でも、まず Google Cloud プロジェクトで Ad Manager API を有効にする必要があります。詳細については、認証をご覧ください。

クライアントライブラリを使用している場合は、環境変数 GOOGLE_APPLICATION_CREDENTIALS をサービスアカウントキーファイルのパスに設定して、アプリケーションのデフォルト認証情報を設定します。詳細については、アプリケーションのデフォルト認証情報の仕組みをご覧ください。

インストール済みアプリケーションの認証情報を使用する場合は、次の形式の JSON ファイルを作成し、代わりにそのパスに環境変数を設定します。

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN",
  "type": "authorized_user"
}

次の値を置き換えます。

CLIENT_ID: 新しいクライアント ID または既存のクライアント ID。
CLIENT_SECRET: 新しいクライアントシークレットまたは既存のクライアントシークレット。
REFRESH_TOKEN: 新しいまたは既存の更新トークン。

Linux または macOSWindows

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

フィルタの違いを理解する

Ad Manager API（ベータ版）のクエリ言語は、パブリッシャークエリ言語（PQL）のすべての機能をサポートしていますが、構文には大きな違いがあります。

Order オブジェクトを一覧表示するこの例は、バインディング変数の削除、大文字と小文字を区別する演算子、ORDER BY 句と LIMIT 句の個別のフィールドへの置き換えなど、主な変更点を示しています。

Ad Manager SOAP API Ad Manager API（ベータ版）

<filterStatement>
  <query>WHERE name like "PG_%" and lastModifiedDateTime &gt;= :lastModifiedDateTime ORDER BY id ASC LIMIT 500</query>
  <values>
    <key>lastModifiedDateTime</key>
    <value xmlns:ns2="https://www.google.com/apis/ads/publisher/v202502" xsi:type="ns2:DateTimeValue">
      <value>
        <date>
          <year>2024</year>
          <month>1</month>
          <day>1</day>
        </date>
        <hour>0</hour>
        <minute>0</minute>
        <second>0</second>
        <timeZoneId>America/New_York</timeZoneId>
      </value>
    </value>
  </values>
</filterStatement>

JSON 形式

{
  "filter": "displayName = \"PG_*\" AND updateTime > \"2024-01-01T00:00:00-5:00\"",
  "pageSize": 500,
  "orderBy":  "name"
}

URL エンコード

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

Ad Manager API（ベータ版）は PQL のすべての機能をサポートしていますが、アドマネージャー SOAP API とは構文が異なります。

Ad Manager API（ベータ版）では、演算子 AND と OR は大文字と小文字が区別されます。小文字の and と or は、フィールド全体を検索する Ad Manager API（ベータ版）の機能である、単純なリテラル検索文字列として扱われます。

大文字の演算子を使用する
```
// Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false
```
小文字はリテラルとして扱われる
```
// Matches unarchived Orders where order.notes has the value 'lorem ipsum'
// and any field in the order has the literal value 'and'.
notes = "lorem ipsum" and archived = false
```
文字 * は、文字列の照合用のワイルドカードです。Ad Manager API（ベータ版）は、like 演算子をサポートしていません。

Ad Manager SOAP API PQL
```
// Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"
```
Ad Manager API（ベータ版）
```
// Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"
```
フィールド名は比較演算子の左側に表示する必要があります。

有効なフィルタ
```
updateTime > "2024-01-01T00:00:00Z"
```
無効なフィルタ
```
"2024-01-01T00:00:00Z" < updateTime
```
Ad Manager API（ベータ版）は、バインディング変数をサポートしていません。すべての値をインライン化する必要があります。
スペースを含む文字列リテラルは、二重引用符で囲む必要があります（例: "Foo bar"）。単一引用符を使用して文字列リテラルをラップすることはできません。

並べ替え句を削除する

アドマネージャー API（ベータ版）では、並べ替え順の指定は任意です。結果セットの並べ替え順序を指定する場合は、PQL ORDER BY 句を削除し、代わりに orderBy フィールドを設定します。

GET networks/${NETWORK_CODE}/orders?orderBy=updateTime+desc

オフセットからページネーショントークンに移行する

Ad Manager API（ベータ版）では、大規模な結果セットのページングに LIMIT 句と OFFSET 句ではなく、ページングトークンを使用します。

Ad Manager API（ベータ版）では、pageSize パラメータを使用してページサイズを制御します。アドマネージャー SOAP API の LIMIT 句とは異なり、ページサイズを省略しても結果セット全体が返されることはありません。代わりに、list メソッドはデフォルトのページサイズ 50 を使用します。次の例では、pageSize と pageToken を URL パラメータとして設定します。

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

Ad Manager SOAP API とは異なり、Ad Manager API（ベータ版）では、追加のページがあっても、リクエストされたページサイズよりも少ない結果が返されることがあります。nextPageToken フィールドを使用して、他に結果があるかどうかを判断します。

ページネーションにオフセットは必要ありませんが、マルチスレッド処理には skip フィールドを使用できます。マルチスレッド処理を行う場合は、最初のページのページネーショントークンを使用して、同じ結果セットから読み取るようにします。

# First thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

# Second thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}&skip=50

Ad Manager SOAP API から移行する

学習

認証

フィルタの違いを理解する

並べ替え句を削除する

オフセットからページネーション トークンに移行する

オフセットからページネーショントークンに移行する