プロダクトに関するご意見やフィードバックをお寄せいただくには、Google 広告および測定のコミュニティサーバーの公式アドマネージャー Discord チャンネルにご参加ください。

Ad Manager SOAP API から移行する

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

次のガイドでは、アドマネージャー SOAP API とアドマネージャー API（ベータ版）の違いについて説明します。

学習

標準の Ad Manager SOAP API サービスメソッドには、Ad Manager API に同等のコンセプトがあります。アドマネージャー 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。
CLIENT_SECRET: 新規または既存のクライアントシークレット。
REFRESH_TOKEN: 新規または既存の更新トークン。

Linux または macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

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

アドマネージャー API（ベータ版）のクエリ言語は、Publisher Query Language（PQL）のすべての機能をサポートしていますが、構文には大きな違いがあります。

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

Ad Manager SOAP 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>

Ad Manager API（ベータ版）

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\"

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

Ad Manager API（ベータ版）では、演算子 AND と OR で大文字と小文字が区別されます。小文字の and と or は、フィールドを横断して検索するアドマネージャー 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
```
文字 * は、文字列照合のワイルドカードです。アドマネージャー 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
```
アドマネージャー API（ベータ版）はバインド変数をサポートしていません。すべての値はインライン化する必要があります。
スペースを含む文字列リテラルは、二重引用符で囲む必要があります（例: "Foo bar"）。文字列リテラルを単一引用符で囲むことはできません。

order by 句を削除する

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

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

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

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

アドマネージャー API（ベータ版）では、pageSize パラメータを使用してページサイズを制御します。Ad Manager SOAP API の LIMIT 句とは異なり、ページサイズを省略しても、結果セット全体が返されることはありません。代わりに、リストメソッドはデフォルトのページサイズ 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}

アドマネージャー SOAP API とは異なり、アドマネージャー 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

レポートを移行する

SOAP API では、非推奨のレポートツールでレポートの読み取りと実行のみを行うことができます。一方、REST API はインタラクティブレポートの読み取り、書き込み、実行のみを行うことができます。

レポートツールと API では異なる ID スペースが使用されます。SOAP API の SavedQuery の ID は REST API では使用できません。

SavedQuery を使用している場合は、レポートを UI のインタラクティブレポートに移行し、2 つの ID スペース間のマッピングを作成できます。レポートの移行について詳しくは、レポートをインタラクティブレポートに移行するをご覧ください。

API の違いを理解する

SOAP API と REST API では、レポートの定義と結果の処理方法にいくつかの違いがあります。

レポートで NAME のみがリクエストされた場合、SOAP API は対応する ID ディメンションを結果に自動的に追加していました。REST API では、結果に含めるには、ID ディメンションを ReportDefinition に明示的に追加する必要があります。
SOAP API には指標の明示的な型がありませんでした。REST API は、Dimension 列挙値でドキュメント化されたデータ型を定義します。ENUM ディメンションはオープン列挙型です。結果を解析する際は、新しい列挙値と不明な列挙値を処理する必要があります。
SOAP API では、Dimensions と DimensionAttributes が分離されていました。REST API には、両方を含む統合された Dimension 列挙型があります。
SOAP API では、ディメンションの数に上限はありませんでした。インタラクティブレポートでは、UI と API の両方でディメンションの数が 10 個に制限されています。同じ ID スペースで分類されるディメンションは、1 つのディメンションとしてカウントされます。たとえば、ORDER_NAME、ORDER_ID、ORDER_START_DATE のみを含める場合、上限の計算では 1 つのディメンションとしてカウントされます。