Publisher Query Language (PQL)-Entwicklerhandbuch

PQL-Syntax und -Verwendung

PQL ist eine SQL-ähnliche Sprache zum Abfragen von Objekten. Die PQL-Syntax ist ähnlich wie bei SQL. Es gibt jedoch ein paar Unterschiede. In diesem Abschnitt wird die PQL-Syntax beschrieben und wie Sie damit verschiedene Objekttypen filtern.

Die PQL-Syntax kann so zusammengefasst werden:

[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 nicht zwischen Groß- und Kleinschreibung unterschieden.
  • Strings werden automatisch in Bindeparametern entkommentiert. Andernfalls:

    • Für eine Zeichenfolge in einfachen Anführungszeichen (Apostrophen) müssen Sie die um einen zusätzlichen Apostroph zu erhalten, indem er als Paar einfache Anführungszeichen geschrieben wird.

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

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

  • WHERE: Stellt eine Reihe von null oder mehr Bedingungen dar, die optional mit AND- oder OR-W��rtern verknüpft werden. Sie können AND- oder OR-Wörtergruppen in Klammern setzen. Wenn Sie die Abfrage "" (leerer String) ausführen, werden alle Daten 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: Verknüpft mehrere Bedingungen, von denen nur eine erfüllt sein muss. Wenn Sie nach einem von mehreren Werten verwenden Sie eine IN-Klausel.

    Beispiel: WHERE width = 728 OR height = 90

  • AND – Mit der AND-Klausel werden mehrere Bedingungen verknüpft, die alle erfüllt sein müssen.

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

  • ORDER BY: sortiert die zurückgegebenen Ergebnisse entweder aufsteigend (ASC, wobei „A“ an erster Stelle steht) oder absteigend (DESC, wobei 'A' der letzte ist) an. Wenn die Richtung nicht festgelegt ist, wird standardmäßig ASC verwendet. Wenn diese Klausel nicht enthalten ist ist der Standardwert für das erste Feld ASC.

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

  • LIMIT: Die Anzahl der zurückzugebenden Ergebnisse. Die LIMIT kann auch einen <offset> enthalten, der Anzahl der Zeilen vom Anfang an, um die Ergebnismenge zu verschieben.

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

  • OFFSET: Der Offset im Ergebnissatz, ab dem Werte zurückgegeben werden sollen. Mit dieser Funktion können Sie die Ergebnisse durchblättern.

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

  • <property>: Eine der vom Objekt freigegebenen Properties. Jedes Objekt bietet verschiedene Eigenschaften, nach denen Sie filtern können. mit PQL; können Sie normalerweise nicht nach allen Attributen filtern, die von einem -Objekt enthält. In der Liste unten sehen Sie, welche Eigenschaften PQL-Abfragen unterstützen. Die Creative-Eigenschaften, nach denen Sie filtern können, umfassen beispielsweise id, name, width und height.
  • <value>: Stringwerte sollten in Anführungszeichen gesetzt werden. einfaches (') Anführungszeichen. Zahlenwerte können in Anführungszeichen oder nicht in Anführungszeichen gesetzt werden. Platzhalter werden nicht unterstützt.
  • IN: Vergleicht den Wert einer Eigenschaft mit jedem Element in einem Liste; wenn eine Übereinstimmung vorliegt, ist es eine positive Übereinstimmung. Das IN entspricht vielen =-Abfragen, eine für jeden Wert, die mit OR verknüpft sind. Die Werte werden als durch Kommas getrennte Liste von Werten angegeben, die in Klammern eingeschlossen sind: (a, b, c). Alle Werte in der Liste sind bewertet.

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

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

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

  • LIKE: Damit können Sie Objekte mithilfe der Platzhalterabfrage abfragen. Das Prozentzeichen (%) steht für null, ein oder mehrere Zeichen. Verwenden Sie ein Paar, um den abzugleichenden Suchstring zu umschließen.

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

  • IS NULL ermöglicht die Abfrage von Objekten mit einem Undefinierter Property-Wert. Das klassische Beispiel dafür ist die Abfrage des Stamm-AdUnit durch Abfrage eines AdUnit-Objekts mit einer Null Parent-ID.

    Beispiel: WHERE parentId IS NULL.

  • <bind variable> – Sie können Value verwenden -Objekte anstelle von hartcodiertem <value> Werte in Ihrer PQL-Abfrage Auf eine Bindevariable 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 id- und status-Eigenschaftswerte 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: Sie können nach Datum und Uhrzeit filtern, indem Sie einer Bindevariablen einen DateTime-Wert zuweisen oder einen String verwenden, der gemäß ISO 8601 formatiert ist. 
    // 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

Match-Tables bieten einen Abgleichmechanismus für die Rohwerte in Datenübertragungsdateien. So können Sie Informationen zur Anzeigenbereitstellung (z. B. Anzeigenblock oder Werbebuchung) mit vorab zugewiesenen Werten in der Datenbank abgleichen.

Wenn Sie Berichte über ReportService oder mit Data Transfer Berichte können Sie Ihre Berichtsdaten durch zusätzliche . Wenn Sie beispielsweise einen Bericht mit der Dimension LINE_ITEM_ID oder ein Datenübertragungsereignis mit dem Feld LineItemId haben, können Sie eine Abgleichtabelle mit dem Start- und Enddatum, dem Typ, dem Status und anderen nützlichen Attributen der einzelnen Positionen erstellen.

Es gibt mehrere Möglichkeiten, diese Abgleichsfunktion zu verwenden:

  1. Verwenden Sie die vordefinierten Match-Tables, die vom BigQuery Data Transfer Service bereitgestellt werden. Diese Abgleichstabellen enthalten nicht alle Entitätsfelder.
  2. Eine effiziente Methode 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 dies durchgehen direkt an den Dienst der Entität, z. B. OrderService.

Python

Berichtsabfrage einrichten

Erstellen Sie zuerst einen Berichtsjob und geben Sie die Berichtsparameter wie Dimensionen, Spalten und 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='v202505')

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 Daten zu Werbebuchungen 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 das Modell pandas da dies die Arbeit mit tabellarischen Daten viel einfacher macht. Hier wird es verwendet, um die Berichtsdaten mit den PQL-Daten zusammenzuführen und eine Abgleichstabelle 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