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. Dieser Abschnitt wird die PQL-Syntax und ihre Verwendung zum Filtern verschiedener Objekttypen beschrieben.

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 maskiert, wenn sie in Binding-Parametern verwendet werden. Andernfalls: <ph type="x-smartling-placeholder">
      </ph>

    • Für eine Zeichenfolge in einfachen Anführungszeichen (Apostrophe) müssen Sie zusätzliche Apostroph, indem wir ihn als Paar einfache Anführungszeichen schreiben.

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

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

  • WHERE: drückt eine Gruppe von null oder mehr Bedingungen aus wahlweise mit UND- oder ODER-Ausdrücken verknüpft werden. Sie können UND- und ODER-Wortgruppen bündeln mit Klammern. Abfrage "" wird ausgeführt (leer) String) gibt alles zurück.

    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. Wenn Sie nach einem von mehreren Werten für ein verwenden Sie eine IN-Klausel.

    Beispiel: WHERE width = 728 OR height = 90

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

    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 – Versatz in der Ergebnismenge, um zu beginnen zurückgegebene Werte. Hiermit können Sie in den Ergebnissen blättern.

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

  • <property> – eine der Eigenschaften, die vom -Objekt enthält. 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 kommagetrennte Liste Werte in Klammern: (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. Das NOT IN entspricht vielen !=-Abfragen, eine für jeden Wert, die mit OR verknüpft sind. Die Werte werden als kommagetrennte Liste Werte in Klammern: (a, b, c). Alle Werte in der Liste sind bewertet.

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

  • LIKE – ermöglicht die Abfrage von Objekten mit einem Platzhalter Stringabgleich. Das Prozentzeichen (%) steht für Null, Eins oder aus mehreren Zeichen bestehen. Verwenden Sie ein Paar, um den Suchstring einzuschließ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 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 Bindung wird in PQL mit einem Stringnamen ohne Leerzeichen durch einen Doppelpunkt (:) zu setzen.

    Beispiel (Erstellt eine Abfrage und gibt zwei Variablen anstelle Hartcodierte id- und status-Eigenschaft Werte):

    // 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 Zuweisen eines DateTime-Werts zu einer Bindungsvariable oder mithilfe eines nach ISO 8601 formatierter String. 
    // 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 Suchmechanismus für die in der Tabelle enthaltenen Rohwerte Mithilfe von Datenübertragungsdateien können Sie Anzeigenschaltungsinformationen (z. B. Einheit oder Position) mit vorab zugewiesenen Werten, die in der Datenbank gespeichert sind.

Wenn Sie Berichte über ReportService oder mit Data Transfer Berichte können Sie Ihre Berichtsdaten durch zusätzliche . Bei einem Bericht mit der Dimension LINE_ITEM_ID oder mit einem Datenübertragungsereignis mit dem Feld LineItemId, können Sie eine Match-Table erstellen, die das Startdatum jeder Werbebuchung enthält. Enddatum, Typ, Status und andere nützliche Attribute.

Dafür gibt es mehrere Möglichkeiten:

  1. Verwenden Sie die vorgefertigten Match-Tables des <ph type="x-smartling-placeholder"></ph> BigQuery Data Transfer Service Beachten Sie, dass diese Match-Tables nicht jedes Entitätsfeld enthalten.
  2. Ein effizienter Ansatz besteht darin, einen 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 zunächst einen Berichtauftrag und geben Sie dabei Ihre Berichtsparameter an, z. B. Dimensionen, Spalten und Zeitraum.

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

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 Funktion Line_Item PQL-Tabelle.

# 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 werden sie um die Berichtsdaten mit den PQL-Daten zusammenzuführen und 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