Struttura della chiamata API

Questa guida descrive la struttura comune di tutte le chiamate API.

Se utilizzi una libreria client per interagire con l'API, non dovrai preoccuparti dei dettagli sottostanti della richiesta. Tuttavia, conoscerli a fondo può essere utile durante i test e il debug.

L'API Google Ads è un'API gRPC con associazioni REST. Ciò significa che ci sono due modi per effettuare chiamate all'API.

1. [Preferito] Crea il corpo della richiesta come buffer di protocollo, invialo al server utilizzando HTTP/2, deserializza la risposta a un buffer di protocollo e interpreta i risultati. La maggior parte della nostra documentazione descrive l'uso di gRPC.

2. [Facoltativo] Crea il corpo della richiesta come oggetto JSON, invialo al server utilizzando HTTP 1.1, deserializza la risposta come oggetto JSON e interpreta i risultati. Per ulteriori informazioni sull'uso di REST, consulta la guida sull'interfaccia REST.

Nota: questa guida descrive la struttura e le intestazioni di trasporto comuni ai protocolli gRPC e REST.

Nomi delle risorse

La maggior parte degli oggetti nell'API sono identificati dalle rispettive stringhe del nome della risorsa. Queste stringhe fungono anche da URL quando si utilizza l'interfaccia REST. Consulta i nomi delle risorse dell'interfaccia REST per conoscerne la struttura.

Punto chiave: consulta la documentazione delle risorse per tutte le risorse supportate e la relativa rappresentazione del percorso (resource_name). Lo stesso formato viene utilizzato per altri servizi.

ID compositi

Se l'ID di un oggetto non è univoco a livello globale, viene creato un ID composto per l'oggetto anteponendo l'ID padre e una tilde (~).

Ad esempio, poiché l'ID annuncio di un gruppo di annunci non è univoco a livello globale, vi anteponiamo l'ID oggetto principale (gruppo di annunci) per creare un ID composto univoco:

• AdGroupId di 123 + ~ + AdGroupAdId di 45678 = ID annuncio composito del gruppo di annunci di 123~45678.

Intestazioni delle richieste

Di seguito sono riportate le intestazioni HTTP (o metadati grpc) che accompagnano il corpo della richiesta:

Autorizzazione

Devi includere un token di accesso OAuth2 nel formato Authorization: Bearer YOUR_ACCESS_TOKEN che identifichi un account amministratore che agisce per conto di un cliente o un inserzionista che gestisce direttamente il proprio account. Per istruzioni su come recuperare un token di accesso, consulta la guida OAuth2. Un token di accesso è valido per un'ora dopo l'acquisizione. Alla scadenza, aggiorna il token di accesso per recuperarne uno nuovo. Tieni presente che le nostre librerie client aggiornano automaticamente i token scaduti.

token-sviluppatore

Un token sviluppatore è una stringa di 22 caratteri che identifica in modo univoco uno sviluppatore di API Google Ads. Una stringa di token per sviluppatori di esempio è ABcdeFGH93KL-NOPQ_STUv. Il token sviluppatore deve essere incluso nel formato developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Questo è l'ID cliente del cliente autorizzato da utilizzare nella richiesta, senza trattini (-). Se l'accesso all'account cliente avviene tramite un account amministratore, questa intestazione è obbligatoria e deve essere impostata sull'ID cliente dell'account amministratore.

Termine chiave: il cliente operativo è l'ID cliente nel payload della richiesta. Ad esempio, il cliente operativo nella seguente richiesta CampaignBudgetService è 1234567890:

https://googleads.googleapis.com/v16/customers/1234567890/campaignBudgets:mutate

Impostare login-customer-id equivale a scegliere un account nell'interfaccia utente di Google Ads dopo aver eseguito l'accesso o aver fatto clic sull'immagine del profilo in alto a destra. Se non la includi, per impostazione predefinita sarà il cliente operativo.

Nota: puoi recuperare l'elenco degli account accessibili direttamente con le tue credenziali OAuth inviando una richiesta CustomerService.ListAccessibleCustomers. login-customer-id non è obbligatorio per questo tipo di richiesta e non ha alcun effetto sull'elenco dei clienti restituiti.

ID-cliente collegato

Questa intestazione viene utilizzata solo dai provider di analisi dati delle app di terze parti durante il caricamento delle conversioni in un account Google Ads collegato.

Considera lo scenario in cui gli utenti dell'account A forniscono accesso in lettura e modifica alle rispettive entità all'account B tramite un ThirdPartyAppAnalyticsLink. Una volta eseguito il collegamento, un utente dell'account B può effettuare chiamate API all'account A, in base alle autorizzazioni fornite dal link. In questo caso, le autorizzazioni di chiamata API per l'account A sono determinate dal link di terze parti all'account B, anziché dalla relazione con l'account amministratore utilizzata in altre chiamate API.

Il provider di analisi dati delle app di terze parti effettua una chiamata API come segue:

• linked-customer-id: l'account Analytics dell'app di terze parti che carica i dati (account B).
• customer-id: l'account Google Ads in cui vengono caricati i dati (account A).
• Intestazione login-customer-id e Authorization: una combinazione di valori per identificare un utente che ha accesso all'account B.

Intestazioni della risposta

Le seguenti intestazioni (o grpc trailing-metadata) vengono restituite con il corpo della risposta. Ti consigliamo di registrare questi valori per scopi di debug.

request-id

request-id è una stringa che identifica in modo univoco questa richiesta.