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 clausolaIN
.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 includonoid
,name
,width
eheight
.<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'operatoreIN
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'operatoreNOT 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'elementoAdUnit
principale tramite query per unAdUnit
con un ID padre nullo.Esempio:
WHERE parentId IS NULL
.<bind variable>
: puoi utilizzare gli oggettiValue
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
estatus
):// 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 valoreDateTime
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:
- 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à.
- Un approccio efficiente consiste nell'utilizzare una qualsiasi delle tabelle PublisherQueryLanguageService disponibili.
- 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