Migracja z interfejsu SOAP Ad Managera

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

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

Informacje

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

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

Uwierzytelnij

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

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

Jeśli używasz danych logowania aplikacji zainstalowanej, 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 klucz tajny 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

Różnice dotyczące filtrów

Język zapytań interfejsu Ad Managera (wersja beta) obsługuje wszystkie funkcje języka zapytań wydawców (PQL), ale występują w nim znaczne różnice w składni.

Ten przykład dotyczący wyświetlania obiektów Order ilustruje główne zmiany, takie jak usunięcie zmiennych wią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>

Ad Manager API (beta)

Format JSON

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

Zakodowany w formacie adresu 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 Ad Managera API (wersja beta) obsługuje wszystkie funkcje PQL, ale różni się od interfejsu Ad Managera SOAP API w tych kwestiach:

  • Operatory AND i OR uwzględniają wielkość liter w interfejsie Ad Managera API (beta). Znaki and i or pisane małymi literami są traktowane jako zwykłe ciągi tekstowe do wyszukiwania. Jest to funkcja interfejsu Ad Manager API (wersja beta), która umożliwia wyszukiwanie w różnych 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ł

    // 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 Ad Managera API (wersja beta) nie obsługuje operatora like.

    Ad Manager SOAP API PQL

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

    Ad Manager API (beta)

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

  • Nazwy pól muszą pojawiać 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 Ad Manager API (wersja beta) nie obsługuje zmiennych wiązanych. Wszystkie wartości muszą być wstawione w treści.

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

Usuwanie klauzul ORDER BY

Określenie kolejności sortowania jest opcjonalne w interfejsie Ad Manager API (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

Przenoszenie z przesunięć na tokeny podziału na strony

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

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

# 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 SOAP API Ad Managera interfejs API Ad Managera (wersja beta) może zwracać mniej wyników niż żądany rozmiar strony, nawet jeśli są dostępne dodatkowe strony. Użyj pola nextPageToken, aby sprawdzić, czy są dostępne dodatkowe wyniki.

Chociaż przesunięcie nie jest wymagane w przypadku podziału na strony, 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 te same wyniki:

# 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

Przenoszenie raportów

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

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

Jeśli korzystasz z SavedQuery, możesz przenieść raport do raportu interaktywnego w interfejsie i utworzyć mapowanie między 2 przestrzeniami identyfikatorów. Więcej informacji o migracji raportów znajdziesz w artykule Migracja raportów do Raportów interaktywnych.

Poznaj różnice między interfejsami API

Istnieją pewne różnice w sposobie, w jaki interfejsy SOAP API i REST API obsługują definicje i wyniki raportów:

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

  • Interfejs SOAP API nie miał jawnych typów danych dotyczących danych. Interfejs REST API definiuje typ danych, który jest udokumentowany w Dimension wartości wyliczeniowej. 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 API REST ma ujednolicony 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ą podzielone według tej samej przestrzeni identyfikatorów, są liczone jako jeden wymiar. Na przykład uwzględnienie tylko ORDER_NAME, ORDER_ID i ORDER_START_DATE liczy się jako 1 wymiar przy obliczaniu limitu.