Migracja z interfejsu SOAP Ad Managera

Interfejs Ad Manager SOAP API to starszy interfejs API do odczytywania i zapisywania danych Ad Managera oraz generowania raportów. Jeśli możesz przeprowadzić migrację, zalecamy korzystanie z interfejsu Ad Manager API (beta). Wersje interfejsu Ad Manager SOAP API są jednak obsługiwane przez typowy okres ich użytkowania. Więcej informacji znajdziesz w harmonogramie wycofywania interfejsu Ad Manager SOAP API Deprecation Schedule.

W tym przewodniku opisano różnice między interfejsem Ad Manager SOAP API a interfejsem API Ad Managera (beta).

Informacje

Standardowe metody usługi Ad Manager SOAP API mają odpowiedniki w interfejsie API Ad Managera. Interfejs API Ad Managera ma też metody odczytywania pojedynczych encji. W tabeli poniżej znajdziesz przykład mapowania metod Order:

Metoda SOAP Metody REST
getOrdersByStatement networks.orders.get
networks.orders.list

Uwierzytelnij

Aby uwierzytelnić się w interfejsie API Ad Managera (beta), możesz użyć dotychczasowych danych logowania do interfejsu Ad Manager SOAP API lub utworzyć nowe. W obu przypadkach musisz najpierw włączyć interfejs Ad Manager API w projekcie Google Cloud. Więcej informacji znajdziesz w artykule Uwierzytelnianie.

Jeśli używasz biblioteki klienta, skonfiguruj domyślne dane logowania aplikacji, ustawiając zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę do pliku klucza konta usługi. Więcej informacji znajdziesz w artykule Jak działa domyślne uwierzytelnianie aplikacji.

Jeśli używasz danych logowania zainstalowanej aplikacji, utwórz plik JSON w tym formacie i ustaw zmienną środowiskową na jego ścieżkę:

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

Zastąp te wartości:

  • CLIENT_ID: nowy lub dotychczasowy identyfikator klienta.
  • CLIENT_SECRET: nowy lub dotychczasowy tajny klucz klienta.

  • REFRESH_TOKEN: nowy lub dotychczasowy token odświeżania.

Linux lub macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Poznaj różnice dotyczące filtrów

Język zapytań interfejsu Ad Manager API (beta) obsługuje wszystkie funkcje języka zapytań wydawcy (PQL), ale występują w nim znaczące różnice w składni.

Ten przykład wyświetlania listy obiektów Order ilustruje główne zmiany, takie jak usunięcie zmiennych powiązanych, operatorów uwzględniających wielkość liter oraz zastąpienie klauzul ORDER BY i LIMIT osobnymi polami:

Interfejs 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>

Interfejs API Ad Managera (beta)

Format JSON

{
  "filter": "displayName = \"PG_*\" AND updateTime > \"2024-01-01T00:00:00-5:00\"",
  "pageSize": 500,
  "orderBy":  "name"
}

Zakodowany adres URL

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

Interfejs API Ad Managera (beta) obsługuje wszystkie funkcje PQL, ale występują w nim te różnice w składni w porównaniu z interfejsem Ad Manager SOAP API:

  • Operatory AND i OR w interfejsie API Ad Managera (beta) uwzględniają wielkość liter. Małe litery and i or są traktowane jako zwykłe literały wyszukiwania, czyli funkcja w interfejsie API Ad Managera (beta) umożliwiająca wyszukiwanie w polach.

    Używaj operatorów pisanych wielkimi literami

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false

    Małe litery traktowane jako literały

    // 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

  • Znak * jest symbolem wieloznacznym do dopasowywania ciągów znaków. Interfejs API Ad Managera (beta) nie obsługuje operatora like.

    PQL interfejsu Ad Manager SOAP API

    // Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"

    Interfejs API Ad Managera (beta)

    // Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"

  • Nazwy pól muszą znajdować się po lewej stronie operatora porównania:

    Prawidłowy filtr

    updateTime > "2024-01-01T00:00:00Z"

    Nieprawidłowy filtr

    "2024-01-01T00:00:00Z" < updateTime

  • Interfejs API Ad Managera (beta) nie obsługuje zmiennych powiązanych. Wszystkie wartości muszą być wstawione w tekście.

  • Literały ciągów znaków zawierające spacje muszą być ujęte w podwójny cudzysłów, np. "Foo bar". Nie można używać pojedynczych cudzysłowów do ujęcia literałów ciągów znaków.

Usuwanie klauzul order by

Określenie kolejności sortowania jest opcjonalne w interfejsie API Ad Managera (beta). Jeśli chcesz określić kolejność sortowania zestawu wyników, usuń klauzulę PQL ORDER BY i ustaw pole orderBy:

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

Migracja z przesunięć na tokeny paginacji

Interfejs API Ad Managera (beta) używa tokenów paginacji zamiast klauzul LIMIT i OFFSET do dzielenia dużych zestawów wyników na strony.

Interfejs API Ad Managera (beta) używa parametru pageSize do kontrolowania rozmiaru strony. W przeciwieństwie do klauzuli LIMIT w interfejsie Ad Manager SOAP API pominięcie rozmiaru strony nie spowoduje zwrócenia całego zestawu wyników. Zamiast tego metoda list używa domyślnego rozmiaru strony 50. W tym przykładzie pageSize i pageToken są ustawione jako parametry adresu URL:

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

W przeciwieństwie do interfejsu Ad Manager SOAP API interfejs Ad Manager API (beta) może zwracać mniej wyników niż żądany rozmiar strony, nawet jeśli są dostępne dodatkowe strony. Aby sprawdzić, czy są dostępne dodatkowe wyniki, użyj pola nextPageToken.

Chociaż przesunięcie nie jest wymagane do paginacji, możesz użyć pola skip do wielowątkowości. W przypadku wielowątkowości użyj tokena paginacji z pierwszej strony, aby mieć pewność, że odczytujesz dane z tego samego zestawu wyników:

# 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

Migracja raportów

Interfejs SOAP API może tylko odczytywać i generować raporty w wycofanym narzędziu Raporty. Z kolei interfejs REST API może tylko odczytywać, zapisywać i generować raporty interaktywne.

Narzędzia i interfejsy API do raportowania mają inne przestrzenie identyfikatorów. Identyfikatora SavedQuery w interfejsie SOAP API nie można używać w interfejsie REST API.

Jeśli używasz SavedQuery, możesz przenieść raport do raportu interaktywnego w interfejsie i utworzyć mapowanie między 2 przestrzeniami identyfikatorów. Więcej informacji o przenoszeniu raportów w interfejsie znajdziesz w artykule Przenoszenie raportów do raportów interaktywnych.

Pełne mapowanie wartości wyliczeniowych SOAP na REST znajdziesz w artykule Dokumentacja raportów.

Poznaj różnice między interfejsami API

Istnieją pewne różnice w sposobie obsługi definicji i wyników raportów przez interfejsy SOAP API i REST API:

  • Interfejs SOAP API automatycznie dodawał do wyników odpowiedni wymiar ID, gdy raport zawierał tylko NAME. W interfejsie REST API musisz wyraźnie dodać wymiar ID do ReportDefinition, aby był on uwzględniany w wynikach.

  • Interfejs SOAP API nie miał wyraźnych typów danych. Interfejs REST API definiuje typ danych, który jest opisany w wartości wyliczeniowej Dimension. Pamiętaj, że wymiary ENUM to otwarte wyliczenia. Podczas analizowania wyników musisz obsługiwać nowe i nieznane wartości wyliczeniowe.

  • Interfejs SOAP API rozdzielał Dimensions i DimensionAttributes. Interfejs REST API ma ujednolicone wyliczenie Dimension, które zawiera oba te elementy.

  • Interfejs SOAP API nie miał limitu liczby wymiarów. Raporty interaktywne mają limit 10 wymiarów zarówno w interfejsie, jak i w interfejsie API. Wymiary, które są dzielone według tej samej przestrzeni identyfikatorów, są liczone jako 1 wymiar. Na przykład uwzględnienie ORDER_NAME, ORDER_ID i ORDER_START_DATE jest liczone jako 1 wymiar podczas obliczania limitu.