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 potrai preoccuparsi dei dettagli sottostanti della richiesta. 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 protocollo buffer e interpreta i risultati. La maggior parte della documentazione descrive l'utilizzo e gRPC.

2. [Facoltativo] Crea il corpo della richiesta come JSON, inviarlo al server tramite HTTP 1.1, deserializzare la risposta come oggetto JSON e interpretare i risultati. Consulta Consulta la guida relativa all'interfaccia REST per avere ulteriori informazioni sull'uso REST.

Nomi delle risorse

La maggior parte degli oggetti nell'API è identificata dalle stringhe dei nomi delle risorse. Questi le stringhe fungono anche da URL quando si utilizza l'interfaccia REST. Vedi il REST i nomi delle risorse dell'interfaccia per alla struttura del centro di costo.

ID composti

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

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

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

Intestazioni delle richieste

Si tratta delle intestazioni HTTP (o grpc metadati) che accompagnano il corpo della richiesta:

Autorizzazione

Devi includere un token di accesso OAuth2 sotto forma di Authorization: Bearer YOUR_ACCESS_TOKEN che identifica un account amministratore che agisce per conto di un cliente o un inserzionista gestire il proprio account. Istruzioni per il recupero di un token di accesso consulta la guida di OAuth2. Un token di accesso sia 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.

developer-token

Un token sviluppatore è una stringa di 22 caratteri che identifica in modo univoco un Sviluppatore dell'API Google Ads. Una stringa di token sviluppatore di esempio è ABcdeFGH93KL-NOPQ_STUv. Il token sviluppatore deve essere incluso nella forma di developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

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

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

Impostare il login-customer-id equivale a scegliere un account nel 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 verrà utilizzato il dell'assistenza clienti.

linked-customer-id

Questa intestazione viene utilizzata solo dai provider di analisi dati delle app di terze parti quando caricare le conversioni in un account Google Ads collegato Google Cloud.

Considera lo scenario in cui gli utenti dell'account A forniscono accesso in lettura e modifica alle rispettive entità per l'account B tramite ThirdPartyAppAnalyticsLink Dopo il collegamento, un utente dell'account B può effettuare chiamate API contro l'account A, in base alle autorizzazioni fornite dal link. In questo caso, la chiamata API le autorizzazioni per l'account A sono determinate dal collegamento di terze parti all'account B invece che nella relazione tra account amministratore e account 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 dell'app di terze parti che carica i dati (account B).
• customer-id: l'account Google Ads su 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 restituiti con il corpo della risposta. Ti consigliamo di registrare questi per il debug.

ID richiesta

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