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

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Ad Manager SOAP API から移行する

Ad Manager SOAP API は、Ad Manager データを読み書きしてレポートを実行するためのレガシー 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 または macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

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

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

Ad Manager API（ベータ版）はすべての PQL 機能をサポートしていますが、Ad Manager 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"）。単一引用符を使用して文字列リテラルを囲むことはできません。

ORDER BY 句を削除する

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

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

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

Ad Manager API（ベータ版）では、ラージアウトプットのページングに LIMIT 句と OFFSET 句ではなく、ページネーショントークンを使用します。

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

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

レポートを移行する

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

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

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

SOAP から REST への列挙値の完全なマッピングについては、レポートのリファレンスをご覧ください。

API の違いを理解する

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

SOAP API では、レポートで NAME のみがリクエストされた場合、対応する ID ディメンションが結果に自動的に追加されます。REST API では、結果に含めるには、ReportDefinition に ID ディメンションを明示的に追加する必要があります。
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 つのディメンションとしてカウントされます。