Чтобы обсудить наши продукты и оставить отзыв о них, присоединяйтесь к официальному каналу Ad Manager Discord на сервере Google Advertising and Measurement Community .

Эта страница переведена с помощью Cloud Translation API.

Переход с SOAP API Менеджера рекламы

API Ad Manager SOAP — это устаревший API для чтения и записи данных Ad Manager, а также для создания отчетов. Если у вас есть возможность миграции, мы рекомендуем использовать API Ad Manager (бета-версия). Однако версии API Ad Manager SOAP поддерживаются в течение их обычного жизненного цикла. Для получения дополнительной информации см. график прекращения поддержки API Ad Manager SOAP.

В данном руководстве описаны различия между SOAP API менеджера рекламы и API менеджера рекламы (бета-версия).

Учиться

Стандартные методы сервиса SOAP API Ad Manager имеют эквивалентные концепции в API Ad Manager. API Ad Manager также содержит методы для чтения отдельных сущностей. Кроме того, действия по изменению состояния, которые ранее использовали один метод perform<Entity>Action в SOAP API, теперь имеют отдельные методы для каждого типа действий в REST API.

В следующей таблице приведен пример сопоставления методов Order :

метод SOAP	REST-методы
`createOrders`	`networks.orders.batchCreate`
`getOrdersByStatement`	`networks.orders.get` `networks.orders.list`
`updateOrders`	`networks.orders.batchUpdate`
`performOrderAction`	Один метод на каждый тип действия. Например: `networks.orders.batchApprove` `networks.orders.batchPause` `networks.orders.batchResume`

Меры реагирования на государственные изменения

В SOAP API perform<Entity>Action возвращал объект UpdateResult с полем numChanges , указывающим, сколько сущностей было изменено. В API Ad Manager (бета-версия) методы пакетных действий возвращают пустой объект ответа. Для определения успешного выполнения действия необходимо проверить его успешность (статус HTTP 200 OK или отсутствие исключения в клиентских библиотеках).

Переименованные и разделенные сервисы

В API Ad Manager некоторые сервисы были переименованы или разделены:

SOAP-сервис	REST-ресурс/сервис
`InventoryService`	`networks.adUnits`
`MobileApplicationService`	`networks.applications`
`CustomTargetingService`	`networks.customTargetingKeys` `networks.customTargetingValues`

Аутентификация

Для аутентификации в API Ad Manager (бета-версия) вы можете использовать существующие учетные данные SOAP API Ad Manager или создать новые. В любом случае, сначала необходимо включить API Ad Manager в вашем проекте Google Cloud. Дополнительные сведения см. в разделе «Аутентификация» .

Если вы используете клиентскую библиотеку, настройте учетные данные приложения по умолчанию, установив переменную среды GOOGLE_APPLICATION_CREDENTIALS , указав путь к файлу ключа вашей учетной записи службы. Дополнительные сведения см. в разделе «Как работают учетные данные приложения по умолчанию» .

Если вы используете учетные данные установленного приложения, создайте JSON-файл в следующем формате и установите переменную среды, указав вместо этого путь к нему:

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

Замените следующие значения:

CLIENT_ID : Ваш новый или существующий идентификатор клиента.
CLIENT_SECRET : Ваш новый или существующий секретный ключ клиента.
REFRESH_TOKEN : Ваш новый или существующий токен обновления.

Linux или macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Понимание названий ресурсов

В API Ad Manager SOAP сущности идентифицируются числовыми идентификаторами Long ID. Связи между сущностями в SOAP также ссылаются на эти числовые идентификаторы.

В API Ad Manager сущности идентифицируются стандартными именами ресурсов , отформатированными в виде строк:

networks/{networkCode}/{collection}/{id}

Например, заказ с идентификатором 123456 в сети 123 имеет имя ресурса networks/123/orders/123456 .

При миграции кода:

Методы, использующие один объект, и методы пакетных действий принимают строковые имена ресурсов, а не числовые идентификаторы.
В связях между сущностями и ссылках на внешние ключи используются имена ресурсов. Например, Order.advertiser это networks/123/companies/456 вместо Order.advertiserId .
Базовое пространство идентификаторов осталось неизменным по сравнению с SOAP. Числовой идентификатор можно извлечь из последнего сегмента имени ресурса.

Разберитесь с обновлениями масок.

В API Ad Manager SOAP методы обновления принимали полные объекты сущностей и обновляли все измененные поля.

В API Ad Manager операции обновления используют маски обновления . Маска обновления определяет, какие поля изменяются во время обновления:

Изменяются только поля, указанные в updateMask . Поля, не включенные в маску, остаются без изменений.
Если параметр updateMask не указан, обновляются все поля, присутствующие в запросе.

Для получения более подробной информации см. раздел «Полевые маски» .

Разберитесь в различиях фильтров.

Язык запросов API Ad Manager (бета-версия) поддерживает все функции языка запросов издателя (PQL), но существуют существенные синтаксические различия.

Этот пример вывода списка объектов Order иллюстрирует основные изменения, такие как удаление переменных привязки, операторов с учетом регистра и замена предложений ORDER BY и LIMIT отдельными полями:

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>

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 Ad Manager (бета-версия) поддерживает все возможности PQL, но отличается от SOAP API Ad Manager следующим синтаксисом:

В API Ad Manager (бета-версия) операторы AND и OR чувствительны к регистру . Строчущие буквы and и or обрабатываются как простые строковые литералы поиска, что является особенностью API Ad Manager (бета-версия) для поиска по полям.
Используйте операторы в верхнем регистре.
```
// 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 Ad Manager (бета-версия) не поддерживает оператор like .
Менеджер рекламы SOAP API PQL
```
// Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"
```
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 Ad Manager (бета-версия) не поддерживает переменные привязки. Все значения должны быть встроены непосредственно в код.
Строковые литералы, содержащие пробелы, должны быть заключены в двойные кавычки, например, "Foo bar" . Одинарные кавычки для заключения строковых литералов недопустимы.

Разберитесь в правилах именования полей.

Названия полей в API Ad Manager соответствуют стандартизированным соглашениям REST и Google Cloud, которые отличаются от SOAP:

Отображаемые имена: Поле name SOAP переименовано в displayName в API Ad Manager. Например, Order.name теперь называется Order.displayName , а AdUnit.name — AdUnit.displayName .
Временные метки: поля SOAP DateTime , такие как lastModifiedDateTime и startDateTime заменяются строковыми временными метками RFC 3339. updateTime и startTime .
Логические значения: Логические поля опускают префиксы, такие как is . Например, isArchived теперь означает archived .

Удалить сортировку по пунктам

В API Ad Manager (бета-версия) указание порядка сортировки является необязательным. Если вы хотите указать порядок сортировки для вашего набора результатов, удалите предложение PQL ORDER BY и вместо этого установите поле orderBy :

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

Переход от смещений к токенам пагинации

API Ad Manager (бета-версия) использует токены пагинации вместо операторов LIMIT и OFFSET для постраничного просмотра больших наборов результатов.

API Ad Manager (бета-версия) использует параметр pageSize для управления размером страницы. В отличие от предложения LIMIT в SOAP API Ad Manager, отсутствие указания размера страницы не возвращает весь набор результатов. Вместо этого метод 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}

В отличие от SOAP API Ad Manager, API Ad Manager (бета-версия) может возвращать меньше результатов, чем запрошенный размер страницы, даже если есть дополнительные страницы. Используйте поле 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

Миграционные отчеты

API SOAP позволяет читать и запускать отчеты только в устаревшем инструменте «Отчеты». В свою очередь, API REST позволяет читать, записывать и запускать только интерактивные отчеты.

Инструменты создания отчетов и API используют разные пространства идентификаторов . Идентификатор объекта SavedQuery в SOAP API нельзя использовать в REST API.

Если вы используете SavedQuery , вы можете перенести отчет в интерактивный отчет через пользовательский интерфейс и создать сопоставление между двумя пространствами идентификаторов. Дополнительную информацию о переносе отчетов через пользовательский интерфейс см. в разделе «Перенос отчетов в интерактивные отчеты» .

Полное сопоставление значений перечислений SOAP и REST см. в справочнике по отчетам .

Разберитесь в различиях API.

Существуют некоторые различия в том, как SOAP API и REST API обрабатывают определения отчетов и результаты:

В SOAP API соответствующий параметр ID автоматически добавлялся к результатам, если отчет запрашивал только NAME . В REST API необходимо явно добавить параметр ID в ReportDefinition , чтобы он был включен в результаты.
В SOAP API не было явных типов для метрик. В REST API определяется тип данных, описанный в значениях перечислений Metric и Dimension . Обратите внимание, что измерения ENUM являются открытыми перечислениями . При разборе результатов необходимо обрабатывать новые и неизвестные значения перечислений.
В SOAP API разделялись Dimensions и DimensionAttributes ). В REST API используется унифицированное перечисление Dimension , содержащее оба типа данных.
В SOAP API не было ограничений на количество измерений. В интерактивных отчетах как в пользовательском интерфейсе, так и в API существует ограничение в 10 измерений. Измерения, которые разбиваются по одному и тому же диапазону идентификаторов, считаются одним измерением. Например, включение ORDER_NAME , ORDER_ID и ORDER_START_DATE учитывается как одно измерение при расчете лимита.

Обработка ошибок

В SOAP API ошибки возвращались как SOAP-сбои и обрабатывались с помощью ApiException с кодами причин, специфичными для сервиса.

API Ad Manager использует стандартные модели ошибок Google Cloud RPC и HTTP:

При возникновении ошибок возвращаются стандартные коды состояния HTTP, такие как 400 INVALID_ARGUMENT , 404 NOT_FOUND или 403 PERMISSION_DENIED .
Подробные сведения об ошибках API, такие как причины нарушения полей, возвращаются в сведениях об ошибке, содержащихся в содержимом файла ошибки.