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 devi preoccuparti dei dettagli della richiesta sottostante. Tuttavia, conoscere un po' di informazioni in merito può essere 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. [Opzione preferita] Crea il corpo della richiesta come buffer del protocollo, invialo al server utilizzando HTTP/2, deserializza la risposta in un buffer del protocollo e interpreta i risultati. La maggior parte della nostra documentazione descrive l'utilizzo 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'utilizzo di REST, consulta la guida all'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 è identificata dalle stringhe dei nomi delle risorse. Queste stringhe fungono anche da URL quando si utilizza l'interfaccia REST. Per la struttura, consulta la sezione Nomi risorse dell'interfaccia REST.

Punto chiave: consulta la documentazione delle risorse per tutte le risorse supportate e la loro 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 composito per quell'oggetto preponendo l'ID principale e una tilde (~).

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

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

Intestazioni delle richieste

Queste sono le intestazioni HTTP (o metadati GRPC) 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 recuperare un token di accesso sono disponibili nella guida OAuth2. Un token di accesso è valido per un'ora dopo l'acquisto. 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 uno sviluppatore dell'API Google Ads. Un esempio di stringa del token sviluppatore è ABcdeFGH93KL-NOPQ_STUv. Il token sviluppatore deve essere incluso nel modulo developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Si tratta dell'ID cliente autorizzato da utilizzare nella richiesta, senza i trattini (-). Se accedi all'account cliente 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 CampaignBudgetService richiesta è 1234567890:

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

L'impostazione di login-customer-id è equivalente alla scelta di 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 viene utilizzato il cliente operativo.

Nota: puoi recuperare l'elenco degli account direttamente accessibili 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.

linked-customer-id

Questo intestazione viene utilizzato 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 accesso in lettura e modifica alle relative entità all'account B tramite un ThirdPartyAppAnalyticsLink. Una volta collegato, un utente dell'account B può effettuare chiamate API all'account A, in base alle autorizzazioni fornite dal collegamento. In questo caso, le autorizzazioni di chiamata dell'API all'account A sono determinate dal collegamento di terze parti all'account A, anziché dal rapporto amministratore-account utilizzato in altre chiamate API.B

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

• linked-customer-id: l'account di analisi dati delle app di terze parti che carica i dati (account B).
• customer-id: l'account Google Ads a cui vengono caricati i dati (accountA).
• 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 il debug.

request-id

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