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 della richiesta sottostanti. Tuttavia, conoscerli un po' può tornare utile durante i test e il debug.

L'API Google Ads è un'API gRPC, con associazioni REST. Ciò significa che esistono 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. Gran parte della 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. Fai riferimento alla guida sull'interfaccia REST per ulteriori informazioni sull'uso di 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 è identificata dalle stringhe dei nomi delle risorse. Queste stringhe fungono anche da URL quando si utilizza l'interfaccia REST. Consulta i nomi delle risorse dell'interfaccia REST per conoscere 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 composti

Se l'ID di un oggetto non è univoco a livello globale, viene creato un ID composto per quell'oggetto anteponendo l'ID principale 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 composto del gruppo di annunci di 123~45678.

Intestazioni delle richieste

Queste sono le intestazioni HTTP (o grpc metadata) che accompagnano il corpo della richiesta:

Autorizzazione

Devi includere un token di accesso OAuth2 sotto forma di 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. Le istruzioni per il recupero di un token di accesso sono disponibili nella guida di OAuth2. Un token di accesso è valido per un'ora dopo l'acquisizione. Quando scade, 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 dell'API Google Ads. Una stringa di token sviluppatore di esempio è ABcdeFGH93KL-NOPQ_STUv. Il token sviluppatore deve essere incluso nel formato developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Si tratta dell'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/v17/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 includi questa intestazione, per impostazione predefinita sarà il cliente operativo.

Nota: puoi recuperare l'elenco di 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 quando caricano le conversioni in un account Google Ads collegato.

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

Il provider di analisi dati delle app di terze parti effettua una chiamata API nel seguente modo:

• linked-customer-id: l'account di analisi dei dati delle 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 a scopo di debug.

request-id

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