Crea report di ricerca nell'API Search Ads 360 Reporting

Leggi le sezioni di seguito per informazioni su come creare report di ricerca negli annunci della rete di ricerca. API di reporting di 360.

Servizio di ricerca

L'API Search Ads 360 Reporting offre un servizio speciale per la ricerca e i report.

SearchAds360Service è un servizio unificato di recupero e reporting di oggetti che offre due metodi di ricerca: SearchStream e Search. Le ricerche sono passato in una stringa di query scritta nel linguaggio di query di Search Ads 360. Puoi definire query per:

• Recuperare attributi specifici degli oggetti.
• Recupera le metriche delle prestazioni per gli oggetti in base a un intervallo di date.
• Ordinare gli oggetti in base ai relativi attributi.
• Filtra i risultati utilizzando condizioni che specificano gli oggetti da restituire
• Limita il numero di oggetti restituiti.

Entrambi i metodi di ricerca restituiscono tutte le righe che corrispondono alla query. Ad esempio, quando recupera campaign.id, campaign.name e metrics.clicks, l'API restituisce un SearchAds360Row contenente un oggetto campagna con i relativi campi id e name e un oggetto metrics con il campo clicks impostato.

Metodi di ricerca

SearchStream

Invia una singola richiesta e avvia una connessione permanente con l'API Search Ads 360 Reporting, indipendentemente dalle dimensioni del report.

• Il download dei pacchetti di dati inizia immediatamente con l'intero risultato memorizzati nella cache in un buffer.
• Il tuo codice può iniziare a leggere i dati presenti nel buffer senza dover attendere l'intero stream per finire.

Search

Invia più richieste impaginate per scaricare l'intero report.

SearchStream in genere offre prestazioni migliori perché elimina tempo di round trip per la richiesta di singole pagine. È consigliabile utilizzare SearchStream per tutti i report con più di 10.000 righe. Non ci sono dati significativi differenza di rendimento tra i metodi per report più piccoli (< 10.000 righe).

Il metodo che utilizzi non influisce su quote e limiti dell'API: una singola query o un singolo report viene conteggiata come un'operazione a prescindere dal fatto che i risultati vengano impaginati o trasmessi in streaming.

Esempio di query di ricerca

Questa query di esempio restituisce i dati sul rendimento di un account per gli ultimi 30 giorni per campagna, segmentati per dispositivo:

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Fai una richiesta

Per emettere una richiesta, devi passare una stringa customer_id e una stringa query alla SearchAds360Service.SearchStream o alla SearchAds360Service.Search a riga di comando.

La richiesta è composta da un POST HTTP all'API Search Ads 360 Reporting server a uno dei seguenti URL:

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

Ecco un esempio completo della definizione del report per searchStream racchiuso tra una richiesta HTTP POST:

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

Elaborare una risposta

SearchAds360Service restituisce un elenco di oggetti SearchAds360Row.

Ciascun SearchAds360Row rappresenta un oggetto restituito dalla query. Ogni oggetto è costituito da un insieme di attributi che vengono compilati in base ai campi richiesti nella clausola SELECT della query. Attributi non inclusi in SELECT non vengono compilate negli oggetti della risposta.

Ad esempio, la query seguente compila ogni oggetto SearchAds360Row solo con il carattere campaign.id, campaign.name e campaign.status. Altri attributi, come campaign.engine_id o campaign.bidding_strategy_type, omessi.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

Documentazione di riferimento

La sezione Riferimento include tutte le informazioni necessarie per utilizzare correttamente ogni artefatto. C'è una pagina per ogni risorsa, ad esempio ad_group e campaign. Le pagine segments e metrics per elencare tutti i segmenti e i campi delle metriche disponibili.

Alcuni segmenti, risorse e metriche non sono compatibili e non possono essere utilizzati mentre le altre sono completamente compatibili e si completano a vicenda. Ciascuna risorsa include le seguenti informazioni (se disponibili e appropriati) e altro ancora:

Risorse attribuite

Per alcune risorse, potresti avere la possibilità di unire implicitamente i risorse selezionando i rispettivi campi insieme a quelli della risorsa in la clausola FROM. Ad esempio, la risorsa campaign è un della risorsa ad_group attribuita. Ciò significa che puoi includi campi come campaign.id e campaign.bidding_strategy_type nel quando utilizzi ad_group nella clausola FROM.

La sezione Risorse attribuite elenca le risorse attribuite disponibili. No tutte le risorse hanno risorse attribuite.

Colonna Campi risorsa

Tutti i campi della risorsa sono inclusi nella colonna Campi risorsa. Ogni campo della risorsa contiene un link a ulteriori dettagli sul campo, tra cui descrizione, categoria, tipo di dati, tipo di URL e ordinabile e ripetuta.

Colonna Segmenti

Non tutti i campi del segmento sono selezionabili con una determinata risorsa.

La colonna Segmenti elenca i campi segments che puoi utilizzare nella stessa clausola SELECT dei campi della risorsa. Ogni campo si collega alla versione completa Dettagli sul campo, tra cui descrizione, categoria, tipo di dati e tipo URL e impostazione filtrabile, selezionabile, ordinabile e ripetuta. Se Utilizzando la risorsa nella clausola FROM, puoi utilizzare il menu a discesa Sì/No per escludere i segmenti che non sono disponibili.

Colonna Metriche

Non tutti i campi delle metriche sono selezionabili per una determinata risorsa.

La colonna Metriche elenca i campi metrics che puoi utilizzare nella stessa clausola SELECT dei campi della risorsa. Ogni campo si collega alla versione completa Dettagli sul campo, tra cui descrizione, categoria, tipo di dati e tipo URL e impostazione filtrabile, selezionabile, ordinabile e ripetuta. Se utilizzando la risorsa nella clausola FROM, usa il menu a discesa Sì/No per escludere le metriche che non sono disponibili.

di Gemini Advanced.

Segmentazione delle risorse

Alcune risorse hanno campi delle risorse di segmentazione che puoi selezionare quando la risorsa si trova nella clausola FROM. Ad esempio, se selezioni un campo risorsa campaign, come campaign.name, quando utilizzando campaign_budget nella clausola FROM, campaign.resource_name verrà automaticamente restituito e segmentato, perché campaign è un risorsa di segmentazione di campaign_budget.

La sezione Segmentazione delle risorse elenca le risorse di segmentazione disponibili. No tutte le risorse hanno risorse di segmentazione.

Selezionabile con

Alcuni campi segments non sono compatibili con altri segmenti, risorse e metriche di valutazione.

La pagina segments include un campo Selezionabile con espandibile per ogni campo segments che elenca tutti i campi delle risorse compatibili, i campi metrics e altri campi segments che puoi includere nella clausola SELECT.

di Gemini Advanced.

Segmentazione

Puoi segmentare i risultati di ricerca aggiungendo un elemento segments.FIELD_NAME alla clausola SELECT della query.

Ad esempio, segments.device nel query sottostante, genera un report con una riga per impressions di ogni dispositivo per la risorsa specificata nella clausola FROM.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

I risultati restituiti da SearchAds360Service.SearchStream hanno un aspetto simile come questa stringa JSON:

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

Visita segments per un elenco dei campi di segmenti disponibili che è possibile utilizzare.

Più segmenti

Puoi specificare più segmenti nella clausola SELECT della query. La risposta contiene un oggetto SearchAds360Row per ogni combinazione del instance della risorsa principale specificata nella clausola FROM e value di ogni campo segment selezionato.

Ad esempio, la seguente query restituirà una riga per ogni combinazione di campaign, segments.ad_network_type e segments.date.

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

Tieni presente che i risultati vengono segmentati in modo implicito in base a ogni istanza dell'istanza principale ma non in base ai valori dei singoli campi selezionati.

La query di esempio seguente genera i risultati in una riga per campagna, non in una riga per distinto del campo campaign.status.

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

Segmentazione implicita

Ogni report viene inizialmente segmentato in base alla risorsa specificata nel campo FROM una clausola. Le metriche sono segmentate in base al campo resource_name di questa risorsa

Questa query di esempio restituisce automaticamente ad_group.resource_name e implicitamente la utilizza per segmentare le metriche a livello di ad_group.

SELECT metrics.impressions
FROM ad_group

La stringa JSON restituita è simile alla seguente:

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

Segmenti di date principali

Puoi utilizzare i segmenti di data principali nella clausola WHERE per specificare una data o un periodo di tempo.

I seguenti campi dei segmenti sono noti come segmenti di date principali: segments.date, segments.week, segments.month, segments.quarter e segments.year.

Questa query di esempio restituisce le metriche della campagna clicks relative agli ultimi 30 giorni.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

I campi dei segmenti di date principali sono un'eccezione alla regola generale che prevede non puoi utilizzare un campo segmenti nella clausola WHERE, a meno che non includi anche il parametro nella clausola SELECT. Per saperne di più, consulta la sezione Filtro vietato informazioni.

Regole principali per i segmenti di date:

• Puoi utilizzare un campo data principale nella clausola WHERE senza includerlo nel Clausola SELECT. Se vuoi, puoi anche includere il campo in entrambe le clausole.

  Questa query di esempio restituisce clicks metriche in base al nome della campagna durante la data intervallo. Tieni presente che segments.date non è incluso nella clausola SELECT.

  SELECT
      campaign.name,
      metrics.clicks
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

• Se includi un campo data principale nella clausola SELECT, devi specificare un valore una data o un intervallo di date limitato nella clausola WHERE. I campi specificati nella sezione Le clausole SELECT e WHERE non devono corrispondere.

  Questa query di esempio restituisce clicks metriche in base al nome della campagna segmentato per mese per tutti i giorni dell'intervallo di date.

  SELECT
    campaign.name,
    metrics.clicks,
    segments.month
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

Date ISO 8601

Puoi utilizzare il formato YYYY-MM-DD (ISO 8601) per specificare date e intervalli di date, Ad esempio:

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

Per i segmenti di date principali che richiedono un periodo di tempo (segments.week, segments.month, segments.quarter) puoi utilizzare l'operatore = con primo giorno del periodo di tempo, ad esempio:

WHERE segments.month = '2022-06-01'

Date predefinite

Puoi anche utilizzare i seguenti intervalli di date e date predefiniti:

Esempio:

WHERE segments.date DURING LAST_30_DAYS

Zero metriche

Quando esegui una query, potresti riscontrare metriche con valore pari a zero per alcune le entità. Scopri come gestire le metriche pari a zero nelle query.

Tipi di enum SCONOSCIUTI

Se una risorsa viene restituita con il tipo di dati enum UNKNOWN, significa che il tipo non è completamente supportato nella versione API. Queste risorse potrebbero sono state create tramite altre interfacce. Ad esempio, una nuova campagna o un nuovo annuncio Sono state introdotte nell'interfaccia utente di Search Ads 360, ma non sono ancora supportate nella versione API. su cui stai eseguendo la query.

Puoi comunque selezionare le metriche quando una risorsa è di tipo UNKNOWN, ma tieni presente quanto segue:

• Una risorsa di tipo UNKNOWN potrebbe essere supportata in un secondo momento, ma potrebbe rimanere UNKNOWN a tempo indeterminato.
• Potrebbero essere visualizzati nuovi oggetti di tipo UNKNOWN in qualsiasi momento. Questi oggetti compatibile con le versioni precedenti perché il valore enum è già disponibile. Introduciamo le risorse con questa modifica quando sono disponibili, in modo che tu possa avere una visualizzazione del tuo account. La risorsa UNKNOWN potrebbe essere visualizzata a causa di nuovi attività nel tuo account tramite altre interfacce o perché una risorsa non diventa più formalmente supportato.
• A UNKNOWN risorsa potrebbero essere associate metriche dettagliate che puoi query.
• Le risorse UNKNOWN sono in genere completamente visibili nell'interfaccia utente di Search Ads 360.