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 conoscere i dettagli della richiesta sottostante. Tuttavia, una certa conoscenza della struttura delle chiamate API può essere utile durante i test e il debug.

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

Preferito:

1. Crea il corpo della richiesta come un buffer di protocollo.
2. Invialo al server utilizzando HTTP/2.
3. Deserializza la risposta in un buffer di protocollo.
4. Interpreta i risultati.

La maggior parte della nostra documentazione descrive l'utilizzo di gRPC.

Facoltativo:

1. Crea il corpo della richiesta come oggetto JSON.
2. Invialo al server utilizzando HTTP 1.1.
3. Deserializza la risposta come oggetto JSON.
4. Interpreta i risultati.

Per ulteriori informazioni sull'utilizzo di REST, consulta la guida all'interfaccia REST.

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

Identificatori di risorse

Gli oggetti nell'API Google Ads vengono indirizzati utilizzando nomi di risorse strutturati e identificatori composti.

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 loro struttura, consulta la sezione Nomi delle risorse dell'interfaccia REST .

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 costruito un ID composto per l'oggetto anteponendo l'ID del relativo elemento principale e una tilde (~).

Ad esempio, un AdGroupAd ha il pattern del nome della risorsa customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Poiché l'identificatore composto combina l'ID del gruppo di annunci principale (ad_group.id) e l'ID dell'annuncio sottostante (ad_group_ad.ad.id), anteponiamo l'ID del gruppo di annunci all'ID dell'annuncio:

• AdGroupId di 123 + ~ + AdId di 45678 = ID annuncio gruppo di annunci composto di 123~45678.

Nota: la condivisione di un AdId in più gruppi di annunci è vietata. La creazione di un nuovo AdGroupAd che fa riferimento a un AdId esistente in un altro gruppo di annunci non riesce con AdGroupAdError.AD_SHARING_NOT_ALLOWED.

Intestazioni delle richieste

Queste sono le intestazioni HTTP (o metadati gRPC) che accompagnano il corpo della richiesta:

Autorizzazione

Devi includere un token di accesso OAuth 2.0 nel formato Authorization: Bearer YOUR_ACCESS_TOKEN che identifica 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'acquisizione; quando scade, aggiorna il token di accesso per recuperarne uno nuovo. Tieni presente che le nostre librerie client aggiornano automaticamente i token scaduti.

Se riscontri errori di autorizzazione, assicurati di utilizzare le credenziali corrette e di disporre delle autorizzazioni sufficienti. Un errore USER_PERMISSION_DENIED indica che l'utente autenticato potrebbe non avere accesso all'account cliente specificato nella richiesta. Se il tuo progetto Google Cloud è approvato solo per l'accesso Test e invii una richiesta che ha come target un account di produzione, l'API restituisce AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION nella versione 25 e successive (o AuthorizationError.ACTION_NOT_PERMITTED nella versione 24 e precedenti). Per informazioni dettagliate sulla gestione delle autorizzazioni, consulta la sezione Livelli di accesso a Google Ads.

login-customer-id

Questo è l'ID cliente del cliente autorizzato da utilizzare nella richiesta, senza trattini (-). Se accedi all'account cliente tramite un account amministratore, questa intestazione è obbligatoria e deve essere impostata sull'ID cliente dell'account amministratore. Se non includi login-customer-id quando esegui l'autenticazione tramite un account amministratore, viene generato un errore AuthorizationError.USER_PERMISSION_DENIED. Per ulteriori informazioni su questo tipo di errore, consulta la sezione Errori comuni. Per una spiegazione dettagliata di come viene risolto l'accesso all'account, consulta la guida al modello di accesso OAuth.

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/v26/customers/1234567890/campaignBudgets:mutate

L'impostazione di 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 viene utilizzato il cliente operativo.

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

linked-customer-id

Questa intestazione è obbligatoria e viene utilizzata dai partner (ad esempio fornitori di analisi delle app di terze parti o partner di dati) quando agiscono su un account Google Ads collegato. Questa intestazione deve specificare l'ID cliente dell'account Google Ads che ha il link al prodotto.

Considera lo scenario in cui un partner deve effettuare chiamate API a un account Google Ads in base a un link al prodotto.

• Inserzionista: l'account Google Ads gestito o aggiornato dalla chiamata API. L'ID dell'account inserzionista è specificato nella richiesta. In REST, questo è il parametro di percorso customerId (ad esempio, customers/1111111111/...), mentre in gRPC è il campo customer_id nella richiesta.
• Partner: l'account partner (ad esempio, un fornitore di analisi delle app di terze parti o un partner di dati).
• Account collegato: l'account Google Ads che ha un link al prodotto stabilito con il partner, che concede al partner l'accesso all' inserzionista.

Un utente che ha accesso all'account partner effettua chiamate API per agire sulle entità nell'account inserzionista (ad esempio, per caricare le conversioni o gestire gli elenchi utenti). L'account collegato può essere l'account inserzionista stesso o un account amministratore dell'account inserzionista.

Le intestazioni delle richieste devono essere impostate come segue:

• Authorization: un token di accesso OAuth 2.0 per un utente che ha accesso al partner.
• login-customer-id: l'ID cliente dell'account partner. L'utente autenticato deve avere accesso a questo account.
• linked-customer-id: l'ID cliente dell'account collegato. Questa intestazione indica che l'autorizzazione per questa richiesta si basa sul link al prodotto dell'account collegato con il partner.

Esistono due scenari di collegamento:

• Se l'account inserzionista ha un link diretto al prodotto con l'account partner , l'account collegato è inserzionista e linked-customer-id deve essere impostato sull'ID cliente dell'account inserzionista.
• Se l'account inserzionista è gestito da un account amministratore che ha un link al prodotto con l'account partner , l'account collegato è l'account amministratore e linked-customer-id deve essere impostato sull'ID cliente del gestore.

Esempio 1: link diretto

Se l'account inserzionista 1111111111 ha un link diretto con l'account partner 2222222222 e la chiamata API ha come target customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Esempio 2: link amministratore

Se l'account inserzionista 1111111111 è gestito dall'account amministratore 3333333333, l'account amministratore 3333333333 ha un link con l'account partner 2222222222 e la chiamata API ha come target customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Intestazioni della risposta

Le seguenti intestazioni (o metadati finali gRPC) 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. Fornisci questo valore quando contatti l'assistenza per risolvere i problemi relativi a richieste API non riuscite o impreviste.