Eseguire la migrazione dall'API SOAP Ad Manager

L'API SOAP di Ad Manager è un'API precedente per leggere e scrivere i dati di Ad Manager e generare report. Se puoi eseguire la migrazione, ti consigliamo di utilizzare l'API Ad Manager (beta). Tuttavia, le versioni dell'API SOAP di Ad Manager sono supportate per il loro ciclo di vita tipico. Per ulteriori informazioni, consulta la Pianificazione del ritiro dell'API SOAP Ad Manager.

La seguente guida illustra le differenze tra l'API SOAP Ad Manager e l'API Ad Manager (beta).

Impara

I metodi di servizio dell'API SOAP di Ad Manager standard hanno concetti equivalenti nell'API Ad Manager. L'API Ad Manager dispone anche di metodi per leggere singole entità. La seguente tabella mostra un esempio di mappatura per i metodi Order:

Metodo SOAP Metodi REST
getOrdersByStatement networks.orders.get
networks.orders.list

Autentica

Per autenticarti con l'API Ad Manager (beta), puoi utilizzare le tue credenziali dell'API SOAP di Ad Manager esistenti o crearne di nuove. Con entrambe le opzioni, devi prima attivare l'API Ad Manager nel tuo progetto Google Cloud. Per ulteriori dettagli, consulta Autenticazione.

Se utilizzi una libreria client, configura le credenziali predefinite dell'applicazione impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave dell'account di servizio. Per maggiori dettagli, consulta Come funzionano le credenziali predefinite dell'applicazione.

Se utilizzi le credenziali dell'applicazione installata, crea un file JSON nel seguente formato e imposta la variabile di ambiente sul relativo percorso:

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

Sostituisci i seguenti valori:

  • CLIENT_ID: il tuo ID client nuovo o esistente.
  • CLIENT_SECRET: il segreto cliente nuovo o esistente.

  • REFRESH_TOKEN: il token di aggiornamento nuovo o esistente.

Linux o macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Differenze tra i filtri

Il linguaggio di query dell'API Ad Manager (beta) supporta tutte le funzionalità del linguaggio di query del publisher (PQL), ma esistono differenze di sintassi significative.

Questo esempio per l'elenco di oggetti Order illustra le modifiche principali, come la rimozione delle variabili di associazione, degli operatori sensibili alle maiuscole e la sostituzione delle clausole ORDER BY e LIMIT con campi separati:

API SOAP Ad Manager 

<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 Ad Manager (beta)

Formato JSON

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

Con codifica URL

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

L'API Ad Manager (beta) supporta tutte le funzionalità PQL, con le seguenti differenze di sintassi rispetto all'API SOAP Ad Manager:

  • Gli operatori AND e OR sono sensibili alle maiuscole nell' API Ad Manager (beta). Le lettere minuscole and e or vengono trattate come stringhe di ricerca litterali senza parametri, una funzionalità dell'API Ad Manager (beta) per eseguire ricerche tra i campi.

    Utilizzare gli operatori in maiuscolo

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

    Minuscole trattate come letterali

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

  • Il carattere * è un carattere jolly per la corrispondenza delle stringhe. L'API Ad Manager (beta) non supporta l'operatore like.

    PQL per l'API SOAP di Ad Manager

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

    API Ad Manager (beta)

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

  • I nomi dei campi devono apparire sul lato sinistro di un operatore di confronto:

    Filtro valido

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

    Filtro non valido

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

  • L'API Ad Manager (beta) non supporta le variabili di binding. Tutti i valori devono essere in linea.

  • I valori letterali stringa contenenti spazi devono essere racchiusi tra virgolette doppie, ad esempio "Foo bar". Non puoi utilizzare le virgolette singole per inserire a capo i valori letterali di stringa.

Rimuovi le clausole di ordinamento per

La specifica di un ordine di ordinamento è facoltativa nell'API Ad Manager (beta). Se vuoi specificare un ordine di ordinamento per il set di risultati, rimuovi la clausola PQL ORDER BY e imposta il campo orderBy:

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

Eseguire la migrazione dagli offset ai token di paginazione

L'API Ad Manager (beta) utilizza token di paginazione anziché clausole LIMIT e OFFSET per la paginazione di set di risultati di grandi dimensioni.

L'API Ad Manager (beta) utilizza un parametro pageSize per controllare le dimensioni della pagina. A differenza della clausola LIMIT nell'API SOAP di Ad Manager, l'omissione di una dimensione pagina non restituisce l'intero insieme di risultati. Il metodo list utilizza invece una dimensione della pagina predefinita di 50. L'esempio seguente imposta pageSize e pageToken come parametri URL:

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

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

A differenza dell'API SOAP Ad Manager, l'API Ad Manager (beta) potrebbe restituire meno risultati rispetto alle dimensioni della pagina richieste anche se sono presenti pagine aggiuntive. Utilizza il campo nextPageToken per determinare se sono presenti altri risultati.

Sebbene un offset non sia necessario per l'impaginazione, puoi utilizzare il campo skip per il multithreading. Quando utilizzi il multithreading, utilizza il token di paginazione della prima pagina per assicurarti di leggere dallo stesso insieme di risultati:

# 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