Przewodnik dla programistów dotyczący języka PQL (Publisher Query Language)

Składnia i użycie PQL

PQL to język podobny do SQL do obsługi zapytań dotyczących obiektów. Składnia PQL jest podobna do składni SQL, z pewnymi różnicami opisanymi tutaj. W tej sekcji opisujemy składnię PQL i pokazujemy, jak używać jej do filtrowania różnych typów obiektów.

Składnia PQL może wyglądać tak:

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

Uwagi

  • W słowach kluczowych PQL wielkość liter nie ma znaczenia.
  • W przypadku ciągów znaków zmiany znaczenia pojawiają się automatycznie, gdy są używane w parametrach powiązania. W przeciwnym razie:

    • W przypadku ciągu z apostrofami pojedynczymi (apostrofami) ucieknij przed każdym dodatkowym apostrofem, wpisując go w parze pojedynczych cudzysłowów.

      Przykład: "WHERE name = 'Company''s name'"

Słowa kluczowe (wielkość liter nie jest rozróżniana)

  • WHERE – zwraca zestaw zawierający 0 lub więcej warunków, opcjonalnie połączone za pomocą wyrażeń I lub LUB. Wyrażenia I i LUB możesz łączyć w grupy z nawiasami. Wykonanie zapytania "" (pusty ciąg znaków) zwraca wszystko.

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

  • OR – łączy wiele warunków, z których tylko jeden musi być spełniony. Jeśli chcesz sprawdzić dowolną z kilku wartości w pojedynczej właściwości, rozważ użycie klauzuli IN.

    Przykład: WHERE width = 728 OR height = 90

  • AND – łączy wiele warunków, które muszą być spełnione za pomocą klauzuli ORAZ.

    Przykład: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB')

  • ORDER BY – sortuje zwrócone wyniki w kolejności rosnącej (ASC, gdzie „A” jest pierwsza) lub malejąco (DESC, gdzie „A” jest ostatnią). Jeśli kierunek nie został określony, domyślnie przyjmuje się ASC. Jeśli ta klauzula nie jest uwzględniona, domyślną wartością jest ASC w pierwszym polu.

    Przykład: WHERE id IN (5008, 8745, 3487) ORDER BY id

  • LIMIT – liczba wyników do zwrócenia. Pole LIMIT może też zawierać wartość <offset>, która określa, ile wierszy od początku zostało do przesuniętego zestawu wyników.

    Przykłady (oba przykłady zwracają ten sam zestaw wyników):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
    WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET – przesunięcie do zbioru wyników, aby rozpocząć zwracanie wartości. Służy do przechodzenia między wynikami.

    Przykład (zwraca wyniki 51–100):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.

  • <property> – jedna z właściwości wyświetlanych przez obiekt. Każdy obiekt ujawnia różne właściwości, według których możesz filtrować za pomocą PQL. Zazwyczaj nie można filtrować według właściwości obsługiwanych przez obiekt. Na liście poniżej możesz sprawdzić, które właściwości obsługują zapytania PQL. Właściwości kreacji, według których możesz filtrować np. id, name, width i height.
  • <value> – wartości ciągu znaków powinny być ujęte w pojedynczy cudzysłów ('). Wartości liczbowe mogą być ujęte w cudzysłów lub bez cudzysłowu. Symbole wieloznaczne nie są obsługiwane.
  • IN – porównuje wartość właściwości z każdym elementem na liście. Jeśli któraś z nich pasuje, uznajemy to za dopasowanie dodatnie. Operator IN jest odpowiednikiem wielu zapytań =, po jednym dla każdej wartości, połączonych operatorem LUB. Wartości te są podane w postaci rozdzielonej przecinkami listy wartości ujętych w nawiasy: (a, b, c). Oceniane są wszystkie wartości na liście.

    Przykład: WHERE name IN ('CompanyNameA', 'CompanyNameB')

  • NOT IN – porównuje wartość właściwości z każdym elementem na liście. Jeśli żadna z nich nie pasuje, oznacza to, że wynik jest dodatni. Operator NOT IN jest odpowiednikiem wielu zapytań !=, po jednym dla każdej wartości, połączonych operatorem LUB. Wartości te są podane w postaci rozdzielonej przecinkami listy wartości ujętych w nawiasy: (a, b, c). Oceniane są wszystkie wartości na liście.

    Przykład: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

  • LIKE – umożliwia wysyłanie zapytań o obiekty z użyciem ciągów znaków wieloznacznych. Znak procentu (%) oznacza zero, jeden lub wiele znaków. Użyj pary, aby uwzględnić wyszukiwany ciąg znaków.

    Przykłady: WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL – umożliwia wysyłanie zapytań o obiekty z niezdefiniowaną wartością właściwości. Klasycznym przykładem jest wysyłanie zapytania o poziom główny AdUnit za pomocą zapytania o obiekt AdUnit z identyfikatorem elementu nadrzędnego o wartości null.

    Przykład: WHERE parentId IS NULL

  • <bind variable> – w zapytaniu PQL zamiast zakodowanych na stałe wartości <value> możesz używać obiektów Value. W PQL odwołanie do zmiennej wiązania jest przy użyciu nazwy ciągu znaków bez spacji i rozpoczynającej się od dwukropka (:).

    Przykład (tworzy zapytanie i wprowadza 2 zmienne zamiast zakodowanych na stałe wartości właściwości id i status):

    // 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);
  • Pola DateTime – możesz filtrować według daty i godziny, przypisując wartość DateTime do zmiennej powiązania lub używając ciągu znaków sformatowanego zgodnie ze standardem 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);

Pobieranie tabel odpowiedników za pomocą PQL

Tabele odpowiedników udostępniają mechanizm wyszukiwania nieprzetworzonych wartości w plikach przenoszenia danych, co pozwala dopasować informacje o wyświetlaniu reklam (np. jednostkę reklamową lub element zamówienia) do wstępnie przypisanych wartości przechowywanych w bazie danych.

Jeśli generujesz raporty za pomocą usługi ReportService lub raportów Przenoszenia danych, możesz uzupełnić dane w raportach o dodatkowe pola. Jeśli na przykład masz raport o wymiarze LINE_ITEM_ID lub zdarzenie przenoszenia danych zawierające pole LineItemId, możesz utworzyć tabelę odpowiedników zawierającą datę rozpoczęcia, datę zakończenia, typ, stan i inne przydatne atrybuty każdego elementu zamówienia.

Tę funkcję można wykorzystać na kilka sposobów:

  1. korzystać z gotowych tabel odpowiedników z BigQuery Data Transfer Service; Zwróć uwagę, że nie zawierają one wszystkich pól encji.
  2. Skutecznym sposobem jest użycie dowolnej z dostępnych tabel PublisherQueryLanguageService.
  3. Jeśli dla encji nie ma tabeli BigQuery ani PQL lub w tabeli brakuje potrzebnych pól, możesz bezpośrednio skorzystać z usługi tej encji, np. OrderService.

Python

Konfigurowanie zapytania dotyczącego raportu

Zacznij od utworzenia zadania raportu i określ parametry raportu, takie jak wymiary, kolumny i zakres dat.

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

Pobieranie raportu

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

Pobierz dane z tabeli PQL elementu zamówienia

Aby dopasować raport do dodatkowych danych elementu zamówienia, możesz użyć tabeli 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)

Łączenie danych raportu z danymi elementów zamówienia

W tym przykładzie korzystamy z biblioteki pandas, ponieważ znacznie ułatwia ona pracę z danymi tabelarycznymi. Służy on do łączenia danych raportu z danymi PQL w celu utworzenia tabeli odpowiedników.

# 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)
Wyświetl w GitHub