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

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

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

Учиться

Стандартные методы обслуживания SOAP API Менеджера рекламы имеют эквивалентные концепции в API Менеджера рекламы. В API Менеджера рекламы также есть методы для чтения отдельных объектов. В следующей таблице показан пример сопоставления методов Order :

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

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

Для аутентификации с помощью API Менеджера рекламы (бета-версия) вы можете использовать существующие учетные данные SOAP API Менеджера рекламы или создать новые. В любом случае вам необходимо сначала включить API Менеджера рекламы в своем проекте 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 : ваш новый или существующий токен обновления.

Линукс или МакОС 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Окна 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Понимание различий в фильтрах

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

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

API SOAP Менеджера рекламы 

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

  • В 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 .

    Менеджер рекламы 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 Менеджера рекламы (бета-версия) не поддерживает переменные привязки. Все значения должны быть встроенными.

  • Строковые литералы, содержащие пробелы, должны быть заключены в двойные кавычки, например, "Foo bar" . Вы не можете использовать одинарные кавычки для заключения строковых литералов.

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

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

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

Миграция со смещений на токены нумерации страниц

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

API Менеджера рекламы (бета-версия) использует параметр pageSize для управления размером страницы. В отличие от предложения LIMIT в SOAP API Менеджера рекламы, отсутствие размера страницы не возвращает весь набор результатов. Вместо этого метод list использует размер страницы по умолчанию 50 . В следующем примере в качестве параметров URL задаются pageSize и pageToken : 

# 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