Guida per gli sviluppatori del Publisher Query Language (PQL)

Sintassi e utilizzo di PQL

PQL è un linguaggio simile a SQL per eseguire query sugli oggetti. La sintassi PQL simile a SQL, con alcune differenze descritte qui. Questa sezione descrive la sintassi PQL e come utilizzarla per filtrare 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 sono sensibili alle maiuscole.
  • Le stringhe presentano caratteri di escape automatici quando vengono utilizzate nei parametri di bind. In caso contrario:

    • Per una stringa tra virgolette singole (apostrofi), esegui l'escape di qualsiasi un apostrofo aggiuntivo scrivendolo come due 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, unito facoltativamente utilizzando frasi AND o OR. Puoi raggruppare frasi AND o OR tra parentesi. Esecuzione della query "" (vuota string) 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, una delle quali deve sia vero. Se vuoi controllare uno tra più valori per un singolo puoi utilizzare una clausola IN.

    Esempio: WHERE width = 728 OR height = 90

  • AND - Unisce più condizioni che devono essere tutte soddisfatti usando la clausola AND.

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

  • ORDER BY: ordina i risultati restituiti in crescente (ASC dove "A" è per prima) o decrescente (DESC dove "A" è l'ultima). Se la direzione non è specificato, il valore predefinito è ASC. Se questa clausola non viene 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. La LIMIT può anche includere un <offset>, che è il numero di righe dall'inizio per eseguire l'offset del set di risultati.

    Esempi (entrambi gli esempi restituiscono lo stesso insieme di risultati):

    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50 WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET: l'offset nel set di risultati all'inizio che restituiscono valori. Utilizzalo per sfogliare i risultati.

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

  • <property> - Una delle proprietà esposte dall'oggetto . Ogni oggetto mostra diverse proprietà in base alle quali puoi filtrare, usando PQL; di solito non è possibile filtrare tutte le proprietà supportate da un , perciò controlla l'elenco riportato di seguito per vedere 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 virgolette singole ('). I valori numerici possono essere racchiusi tra virgolette o non tra virgolette. Caratteri jolly non sono supportati.
  • IN: confronta il valore di una proprietà per ogni elemento in una elenco; se c'è corrispondenza, è una corrispondenza positiva. IN equivale a molte query =, una per ogni valore, con OR insieme. I valori vengono specificati come elenco separato da virgole di racchiusi tra parentesi: (a, b, c). Tutti i valori nell'elenco vengono viene valutato.

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

  • NOT IN: confronta il valore di una proprietà per ogni elemento in un elenco; se nessuna corrispondenza, è positiva. NOT IN equivale a molte query !=, una per ogni valore, con OR insieme. I valori vengono specificati come elenco separato da virgole di racchiusi tra parentesi: (a, b, c). Tutti i valori nell'elenco vengono viene valutato.

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

  • LIKE: consente di eseguire query sugli oggetti utilizzando un carattere jolly la corrispondenza delle stringhe. Il segno della 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 per oggetti con un valore della proprietà non definito. Il classico esempio è l'esecuzione di query per il root AdUnit eseguendo una query per un AdUnit con un valore null l'ID principale.

    Esempio: WHERE parentId IS NULL.

  • <bind variable> - Puoi usare Value al posto dell'elemento <value> impostato come hardcoded nella tua query PQL. Un vincolo viene indicata in PQL utilizzando un nome stringa senza spazi, a partire da con i punti : (:).

    Esempio (crea una query e inserisce due variabili al posto di proprietà id e status hardcoded di sicurezza):

    // 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 per assegnando un valore DateTime a una variabile di associazione oppure utilizzando un 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 all'interno di file Data Transfer, che ti consentono di associare le informazioni sulla pubblicazione di annunci (come unità o elemento pubblicitario) ai valori preassegnati e memorizzati nel database.

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

Esistono diversi modi per realizzare questa funzionalità di corrispondenza:

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

Python

Impostare una query di report

Per iniziare, crea un job di report e specifica 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='v202408')

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 Line_Item PQL

Per associare il report a dati aggiuntivi relativi agli elementi pubblicitari, puoi utilizzare il valore Line_Item dalla tabella PQL.

# 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 ai dati degli elementi pubblicitari

In questo esempio viene utilizzato il comando pandas poiché semplifica l'uso dei dati tabulari. In questo caso viene utilizzato per unire i dati del report a quelli 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