Guida per gli sviluppatori del Publisher Query Language (PQL)

Sintassi e utilizzo PQL

PQL è un linguaggio simile a SQL per eseguire query sugli oggetti. La sintassi PQL è simile a quella di SQL, con alcune differenze descritte in questo articolo. Questa sezione descrive la sintassi PQL e come utilizzarla per filtrare i vari tipi di oggetti.

La sintassi PQL può essere riassunta come segue:

[WHERE <condition> {[AND | OR] <condition> ...}]
[ORDER BY <property> [ASC | DESC]]
[LIMIT {[<offset>,] <count>} | {<count> OFFSET <offset>}]

<condition> := <property> { = | != } <value>
<condition> := <property> { = | != } <bind variable>
<condition> := <property> IN <list>
<condition> := NOT <property> IN <list>
<condition> := <property> LIKE <wildcard%match>
<condition> := <property> IS NULL
<bind variable> := :<name>

Note

  • Le parole chiave PQL non fanno distinzione tra maiuscole e minuscole.
  • Quando vengono utilizzate nei parametri di associazione, le stringhe vengono convertite automaticamente in caratteri di escape. In caso contrario:
    • Per una stringa tra virgolette singole (apostrofi), esegui l'escape di qualsiasi apostrofo aggiuntivo scrivendolo come coppia di virgolette singole.

      Esempio: "WHERE name = 'Company''s name'"

Parole chiave (senza distinzione tra maiuscole e minuscole)

  • WHERE: esprime un insieme di zero o più condizioni, facoltativamente unite utilizzando le frasi AND o OR. Puoi raggruppare le frasi AND oppure OR tra le parentesi. L'esecuzione della query "" (stringa vuota) restituisce tutto.

    Esempi: WHERE width = 728
    WHERE width = 728 AND height = 90
    WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)

  • OR: unisce più condizioni, solo una delle quali deve essere vera. Se vuoi controllare uno o più valori per una singola proprietà, valuta la possibilità di utilizzare una clausola IN.

    Esempio: WHERE width = 728 OR height = 90

  • AND: unisce più condizioni che devono essere tutte soddisfatte utilizzando la clausola AND.

    Esempio: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB')

  • ORDER BY: ordina i risultati restituiti in ordine crescente (ASC, dove "A" è la prima) o decrescente (DESC dove "A" è l'ultima). Se la direzione non viene specificata, il valore predefinito è ASC. Se questa clausola non è inclusa, il valore predefinito è ASC nel primo campo.

    Esempio: WHERE id IN (5008, 8745, 3487) ORDER BY id

  • LIMIT: il numero di risultati da restituire. LIMIT può anche includere un <offset>, ovvero il numero di righe dall'inizio per correggere l'offset del set di risultati.

    Esempi (entrambi gli esempi restituiscono lo stesso set di risultati):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
    WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET: l'offset nel set di risultati per iniziare a restituire i valori. Utilizza questa opzione per sfogliare i risultati.

    Esempio (restituisce i risultati 51-100):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.

  • <property>: una delle proprietà esposte dall'oggetto. Ogni oggetto espone diverse proprietà in base alle quali puoi applicare il filtro utilizzando PQL. Generalmente non puoi filtrare in base a tutte le proprietà supportate da un oggetto, perciò controlla l'elenco riportato di seguito per verificare quali proprietà supportano le query PQL. Ad esempio, le proprietà della creatività in base alle quali puoi filtrare includono id, name, width e height.
  • <value>: i valori delle stringhe devono essere racchiusi tra virgolette singole ('). I valori numerici possono essere racchiusi tra virgolette o senza virgolette. I caratteri jolly non sono supportati.
  • IN: confronta il valore di una proprietà con ogni elemento dell'elenco ; se esiste una corrispondenza, si tratta di una corrispondenza positiva. L'operatore IN equivale a molte query =, una per ogni valore, collegate tra loro tramite OR. I valori sono specificati come elenco di valori separati da virgole, racchiusi tra parentesi: (a, b, c). Vengono valutati tutti i valori nell'elenco.

    Esempio: WHERE name IN ('CompanyNameA', 'CompanyNameB')

  • NOT IN: confronta il valore di una proprietà con ogni elemento in un elenco. Se non esistono corrispondenze, si tratta di una corrispondenza positiva. L'operatore NOT IN equivale a molte query !=, una per ogni valore, collegate tra loro tramite OR. I valori sono specificati come elenco di valori separati da virgole, racchiusi tra parentesi: (a, b, c). Vengono valutati tutti i valori nell'elenco.

    Esempio: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

  • LIKE: consente di eseguire query su oggetti utilizzando la corrispondenza delle stringhe con caratteri jolly. Il segno percentuale (%) rappresenta zero, uno o più caratteri. Utilizza una coppia per racchiudere la stringa di ricerca corrispondente.

    Esempi: WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL: consente di eseguire query su oggetti con un valore di proprietà non definito. Nell'esempio classico, viene eseguita una query per l'elemento AdUnit principale tramite query per un AdUnit con un ID padre nullo.

    Esempio: WHERE parentId IS NULL.

  • <bind variable>: puoi utilizzare gli oggetti Value al posto dei valori <value> hardcoded nella query PQL. A una variabile di associazione viene fatto riferimento in PQL utilizzando un nome stringa senza spazi, che inizia con : (due punti).

    Esempio (crea una query e inserisce due variabili al posto dei valori hardcoded delle proprietà id e status):

    // Create two mapped parameters: id and status
    String_ValueMapEntry[] values = new String_ValueMapEntry[2];
    values[0] = new String_ValueMapEntry("id", new NumberValue(null, "123"));
    values[1] = new String_ValueMapEntry("status", new TextValue(null, "APPROVED"));
    
    // Create our statement and map our bind variables
    Statement statement = new Statement();
    statement.setQuery("WHERE id = :id AND status = :status LIMIT 500");
    statement.setValues(values);
  • Campi DateTime: puoi filtrare per data e ora assegnando un valore DateTime a una variabile di associazione o utilizzando una stringa formattata secondo lo standard ISO 8601.
    // Create a bind variable: startDateTime
    String_ValueMapEntry[] values = new String_ValueMapEntry[1];
    values[0] = new String_ValueMapEntry("startDateTime", new DateTimeValue(null, dateTime));
    
    // Create our statement and map our bind variables
    Statement statement = new Statement();
    statement.setQuery("WHERE endDateTime < '2019-01-01T00:00:00' AND startDateTime > :startDateTime LIMIT 500");
    statement.setValues(values);

Recupero delle tabelle delle corrispondenze con PQL

Le tabelle delle corrispondenze forniscono un meccanismo di ricerca per i valori non elaborati contenuti nei file Data Transfer, consentendoti di associare le informazioni sulla pubblicazione di annunci (come unità pubblicitaria o elemento pubblicitario) ai valori preassegnati e memorizzati nel database.

Se esegui i report tramite ReportService o con report Data Transfer, ti consigliamo di integrare i dati del report con altri campi. Ad esempio, con un report con la dimensione LINE_ITEM_ID o con un evento di trasferimento dati con campo LineItemId, puoi creare una tabella delle corrispondenze che include la data di inizio, la data di fine, il tipo, lo stato e altri attributi utili di ogni elemento pubblicitario.

Esistono diversi modi per eseguire questa funzionalità di corrispondenza:

  1. Utilizza le tabelle delle corrispondenze predefinite fornite da BigQuery Data Transfer Service. Tieni presente che queste tabelle delle corrispondenze non contengono tutti i campi dell'entità.
  2. Un approccio efficiente consiste nell'utilizzare una qualsiasi delle tabelle PublisherQueryLanguageService disponibili.
  3. Se non esiste una tabella BigQuery o PQL per l'entità o se nella tabella mancano i campi necessari, puoi utilizzare direttamente il servizio dell'entità, ad esempio OrderService.

Python

Impostare una query report

Per iniziare, crea un job di report, specificando i parametri del report come dimensioni, colonne e intervallo di date.

# Set the start and end dates of the report to run (past 8 days).
end_date = date.today()
start_date = end_date - timedelta(days=8)

# Create report job.
report_job = {
    'reportQuery': {
        'dimensions': ['LINE_ITEM_ID', 'LINE_ITEM_NAME'],
        'columns': ['AD_SERVER_IMPRESSIONS', 'AD_SERVER_CLICKS',
                    'AD_SERVER_CTR', 'AD_SERVER_CPM_AND_CPC_REVENUE',
                    'AD_SERVER_WITHOUT_CPD_AVERAGE_ECPM'],
        'dateRangeType': 'CUSTOM_DATE',
        'startDate': start_date,
        'endDate': end_date
    }
}

Scarica il report

# Initialize a DataDownloader.
report_downloader = client.GetDataDownloader(version='v202402')

try:
  # Run the report and wait for it to finish.
  report_job_id = report_downloader.WaitForReport(report_job)
except errors.AdManagerReportError as e:
  print('Failed to generate report. Error was: %s' % e)

with tempfile.NamedTemporaryFile(
    suffix='.csv.gz', mode='wb', delete=False) as report_file:
  # Download report data.
  report_downloader.DownloadReportToFile(
      report_job_id, 'CSV_DUMP', report_file)

Scarica i dati dalla tabella PQL Line_Item

Per creare una corrispondenza tra il report e altri dati sugli elementi pubblicitari, puoi utilizzare la tabella PQL Line_Item.

# Create a PQL query to fetch the line item data
line_items_pql_query = ('SELECT Id, LineItemType, Status FROM LineItem')

# Download the response from PQL select statement
line_items = report_downloader.DownloadPqlResultToList(line_items_pql_query)
    

Unire i dati del report con i dati degli elementi pubblicitari

Questo esempio utilizza la libreria panda in quanto semplifica molto l'utilizzo dei dati tabulari. Viene utilizzato per unire i dati del report con i dati PQL per creare una tabella delle corrispondenze.

# Use pandas to join the two csv files into a match table
report = pandas.read_csv(report_file.name)
line_items = pandas.DataFrame(data=line_items[1:], columns=line_items[0])
merged_result = pandas.merge(report, line_items,
                             left_on='Dimension.LINE_ITEM_ID', right_on='id')
merged_result.to_csv('~/complete_line_items_report.csv', index=False)
Visualizza su GitHub