Publisher Query Language (PQL)-Entwicklerhandbuch

PQL-Syntax und -Nutzung

PQL ist eine SQL-ähnliche Sprache zum Abfragen von Objekten. Die PQL-Syntax ähnelt der von SQL. Es gibt aber einige Unterschiede. In diesem Abschnitt werden die PQL-Syntax und ihre Verwendung zum Filtern verschiedener Objekttypen beschrieben.

Die PQL-Syntax lässt sich so zusammenfassen:

[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>

Hinweise

  • Bei PQL-Keywords wird die Groß-/Kleinschreibung nicht berücksichtigt.
  • Strings werden automatisch maskiert, wenn sie in Bindungsparametern verwendet werden. Andernfalls gehen Sie so vor:

    • Maskieren Sie bei einem String in einfachen Anführungszeichen (Apostrophe) jeden zusätzlichen Apostroph, indem Sie ihn als ein Paar einfacher Anführungszeichen schreiben.

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

Keywords (Groß-/Kleinschreibung nicht berücksichtigend)

  • WHERE: drückt einen Satz von null oder mehr Bedingungen aus, die optional mit UND- oder ODER-Wortgruppen verbunden werden. Sie können UND- oder ODER-Wortgruppen mit Klammern bündeln. Bei Ausführung der Abfrage "" (leerer String) wird alles zurückgegeben.

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

  • OR: Verbindet mehrere Bedingungen, von denen nur eine wahr sein muss. Wenn Sie auf mehrere Werte für eine einzelne Property prüfen möchten, sollten Sie eine IN-Klausel verwenden.

    Beispiel: WHERE width = 728 OR height = 90

  • AND: Verbindet mehrere Bedingungen, die alle erfüllt sein müssen, mithilfe der AND-Klausel.

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

  • ORDER BY: Sortiert die zurückgegebenen Ergebnisse entweder in aufsteigender (ASC, wobei „A“ an erster Stelle) oder absteigend (DESC, wenn „A“ die letzte ist) Reihenfolge. Wenn keine Richtung angegeben ist, wird standardmäßig ASC verwendet. Wenn diese Klausel nicht enthalten ist, wird im ersten Feld der Standardwert ASC verwendet.

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

  • LIMIT – Anzahl der Ergebnisse, die zurückgegeben werden sollen. Die LIMIT kann auch eine <offset> enthalten. Diese gibt an, wie viele Zeilen vom Anfang aus den Ergebnissatz verschieben müssen.

    Beispiele (beide Beispiele geben dieselbe Ergebnismenge zurück):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
    WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET: Der Offset in der Ergebnismenge, ab dem Werte zurückgegeben werden sollen. Hiermit können Sie durch die Ergebnisse blättern.

    Beispiel (gibt Ergebnisse 51–100 zurück):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.

  • <property>: Eine der vom Objekt zur Verfügung gestellten Attribute. Jedes Objekt bietet verschiedene Attribute, nach denen Sie mithilfe von PQL filtern können. Normalerweise ist es nicht möglich, nach allen Attributen zu filtern, die von einem Objekt unterstützt werden. In der folgenden Liste sehen Sie, welche Attribute PQL-Abfragen unterstützen. Zu den Creative-Eigenschaften, nach denen Sie filtern können, gehören beispielsweise id, name, width und height.
  • <value>: Stringwerte müssen in einfache (') Anführungszeichen gesetzt werden. Zahlenwerte können in Anführungszeichen gesetzt werden. Platzhalter werden nicht unterstützt.
  • IN: vergleicht den Wert einer Eigenschaft mit jedem Element in einer Liste. Wenn eine Übereinstimmung übereinstimmt, ist es eine positive Übereinstimmung. Der Operator IN entspricht vielen =-Abfragen (eine für jeden Wert), die über OR verbunden sind. Die Werte werden als durch Kommas getrennte Liste von Werten in Klammern angegeben: (a, b, c). Alle Werte in der Liste werden ausgewertet.

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

  • NOT IN: vergleicht den Wert einer Eigenschaft mit jedem Element in einer Liste. Wenn keine Übereinstimmung vorhanden ist, ist es eine positive Übereinstimmung. Der Operator NOT IN entspricht vielen !=-Abfragen (eine für jeden Wert), die über OR verbunden sind. Die Werte werden als durch Kommas getrennte Liste von Werten in Klammern angegeben: (a, b, c). Alle Werte in der Liste werden ausgewertet.

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

  • LIKE: ermöglicht die Abfrage von Objekten mit Platzhalterstringabgleichen. Das Prozentzeichen (%) steht für null, ein oder mehrere Zeichen. Verwenden Sie ein Paar, um den Suchstring umzuschließen, der abgeglichen werden soll.

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

  • IS NULL: Ermöglicht die Abfrage von Objekten mit einem nicht definierten Attributwert. Das klassische Beispiel ist die Abfrage des Stamm-AdUnit durch Abfrage eines AdUnit-Objekts mit einer übergeordneten ID, die null hat.

    Beispiel: WHERE parentId IS NULL.

  • <bind variable>: Sie können in der PQL-Abfrage Value-Objekte anstelle von hartcodierten <value>-Werten verwenden. Auf eine Bindungsvariable wird in PQL mit einem Stringnamen ohne Leerzeichen verwiesen, der mit einem Doppelpunkt (:) beginnt.

    Beispiel (erstellt eine Abfrage und gibt zwei Variablen anstelle der hartcodierten Attributwerte id und status ein):

    // 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);
  • DateTime-Felder: Zum Filtern nach Datum und Uhrzeit können Sie einer Bind-Variablen einen DateTime-Wert zuweisen oder einen gemäß ISO 8601 formatierten String verwenden. 
    // 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);

Match-Tables mit PQL abrufen

Übereinstimmungstabellen bieten einen Suchmechanismus für die Rohwerte in den Datenübertragungsdateien. So können Sie Anzeigenbereitstellungsinformationen (wie Anzeigenblock oder Werbebuchung) mit zugeordneten Werten in der Datenbank abgleichen.

Wenn Sie Berichte mit ReportService oder Datenübertragungsberichten generieren, können Sie die Berichtsdaten durch zusätzliche Felder ergänzen. Sie können beispielsweise mit einem Bericht mit der Dimension LINE_ITEM_ID oder einem Datenübertragungsereignis mit dem Feld LineItemId eine Match-Table erstellen, die Start- und Enddatum, Typ, Status und andere nützliche Attribute jeder Werbebuchung enthält.

Es gibt mehrere Möglichkeiten, diese Abgleichfunktion zu erreichen:

  1. Verwenden Sie die vom BigQuery Data Transfer Service bereitgestellten vordefinierten Match-Tables. Beachten Sie, dass diese Match-Tables nicht alle Entitätsfelder enthalten.
  2. Ein effizienter Ansatz ist die Verwendung einer der verfügbaren PublisherQueryLanguageService-Tabellen.
  3. Wenn für die Entität keine BigQuery- oder PQL-Tabelle vorhanden ist oder in der Tabelle erforderliche Felder fehlen, können Sie den Dienst der Entität direkt aufrufen, z. B. OrderService.

Python

Berichtsabfrage einrichten

Erstellen Sie zuerst einen Berichtauftrag und geben Sie Ihre Berichtsparameter wie Dimensionen, Spalten und den Zeitraum an.

# 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
    }
}

Bericht herunterladen

# 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)

Daten aus der PQL-Tabelle „Line_Item“ herunterladen

Wenn Sie Ihren Bericht mit zusätzlichen Werbebuchungsdaten abgleichen möchten, können Sie die PQL-Tabelle Line_Item verwenden.

# 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)

Berichtsdaten mit Werbebuchungsdaten zusammenführen

In diesem Beispiel wird die pandas-Bibliothek verwendet, da sie die Arbeit mit tabellarischen Daten erheblich erleichtert. Hier werden die Berichtsdaten mit den PQL-Daten zusammengeführt, um eine Match-Table zu erstellen.

# 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)
Auf GitHub ansehen