Переход с 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 также содержит методы для чтения отдельных сущностей. В следующей таблице показан пример сопоставления методов Order :

метод SOAP REST-методы
getOrdersByStatement networks.orders.get
networks.orders.list

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

Для аутентификации в 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 (бета-версия) поддерживает все функции языка запросов издателя (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 (бета-версия) указание порядка сортировки является необязательным. Если вы хотите указать порядок сортировки для вашего набора результатов, удалите предложение 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 , вы можете преобразовать отчет в интерактивный отчет в пользовательском интерфейсе и создать сопоставление между двумя пространствами идентификаторов. Дополнительную информацию о преобразовании отчетов см. в разделе «Преобразование отчетов в интерактивные отчеты» .

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

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

  • В SOAP API соответствующий параметр ID автоматически добавлялся к результатам, если отчет запрашивал только NAME . В REST API необходимо явно добавить параметр ID в ReportDefinition , чтобы он был включен в результаты.

  • В SOAP API не было явных типов для метрик. В REST API определяется тип данных, описанный в значении перечисления Dimension . Обратите внимание, что измерения ENUM являются открытыми перечислениями . При разборе результатов необходимо обрабатывать новые и неизвестные значения перечислений.

  • В SOAP API разделялись Dimensions и DimensionAttributes ). В REST API используется унифицированное перечисление Dimension , содержащее оба типа данных.

  • В SOAP API не было ограничений на количество измерений. В интерактивных отчетах как в пользовательском интерфейсе, так и в API существует ограничение в 10 измерений. Измерения, которые разбиваются по одному и тому же диапазону идентификаторов, считаются одним измерением. Например, включение ORDER_NAME , ORDER_ID и ORDER_START_DATE учитывается как одно измерение при расчете лимита.