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

Składnia i zastosowanie PQL

PQL to język podobny do SQL służący do wysyłania zapytań do obiektów. Składnia PQL jest podobna do składni SQL, ale występują pewne różnice, które opisaliśmy poniżej. Ta sekcja opisuje składnię PQL i opisuje, jak używać jej do filtrowania różnych typów obiektów.

Składnię PQL można podsumować w ten sposób:

[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.
  • Ciągi znaków są automatycznie ujęte w znaki ucieczki, gdy są używane w parametrach bind. W innym przypadku:

    • W przypadku ciągu znaków w pojedynczych cudzysłowach (apostrofów) zmień znaczenie dowolnego ciągu jako dodatkowy apostrof, zapisując go jako parę pojedynczych cudzysłowów.

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

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

  • WHERE – wyraża zbiór zero lub więcej warunków, opcjonalnie połączone za pomocą wyrażeń AND i OR. Wyrażenia I i LUB są łączone w grupy, w nawiasach. Wykonywanie 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ć prawdziwy. Jeśli chcesz sprawdzić, czy dana właściwość ma dowolną z kilku wartości, użyj klauzuli IN.

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

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

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

  • ORDER BY – sortuje wyniki w jednej z tych rosnąco (ASC, gdzie „A” jest pierwsze) lub malejąco (DESC, gdzie „A” to ostatnie). Jeśli nie podasz kierunku, zostanie użyta wartość domyślna ASC. Jeśli ta klauzula nie jest uwzględniona, domyślną wartością pierwszego pola jest ASC.

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

  • LIMIT – liczba wyników do zwrócenia. LIMIT może też zawierać <offset>, czyli liczbę wierszy od początku zbioru wyników.

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

  • OFFSET – przesunięcie w zbiorze wyników, od którego mają się zaczynać zwracane wartości. Służy do przeglądania wyników.

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

  • <property> – jedna z właściwości udostępnianych przez tag obiektu. Każdy obiekt ujawnia różne właściwości, według których można filtrować, używając PQL; z reguły nie można filtrować według wszystkich właściwości obsługiwanych przez obiektu. Sprawdź na liście poniżej, które właściwości obsługują zapytania PQL. Na przykład właściwości kreacji, według których możesz filtrować, zawierają id, name, width i height.
  • <value> – ciągi znaków powinny być ujęte w cudzysłów pojedynczy cudzysłów ('). Wartości liczbowe mogą być w cudzysłowie lub bez cudzysłowów. Symbole wieloznaczne nie są obsługiwane.
  • IN – porównuje wartość właściwości z każdym elementem w kolumnie list; jeśli któraś z nich jest zgodna, jest to dopasowanie dodatnie. Operator IN jest równoważny wielu zapytaniom =, po jednym dla każdej wartości, które są połączone operatorem LUB. Wartości są podawane jako lista wartości rozdzielonych przecinkami, zamknięta w nawiasach: (a, b, c). Wszystkie wartości na liście są oceniono.

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

  • NOT IN – porównuje wartość właściwości z poszczególnymi elementami. na liście; jeśli żadna z nich nie pasuje, jest zgodna z dodatnią. NOT IN jest odpowiednikiem wielu zapytań !=, po jednym dla każdej wartości, połączonych operatorem LUB. Wartości są podawane jako lista wartości rozdzielonych przecinkami, zamknięta w nawiasach: (a, b, c). Wszystkie wartości na liście są oceniono.

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

  • LIKE – umożliwia wysyłanie zapytań dotyczących obiektów przy użyciu symboli wieloznacznych. dopasowania ciągu. Znak procenta (%) oznacza 0, 1 lub wiele znaków. Użyj pary do ujmowania dopasowanego ciągu wyszukiwania.

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

  • IS NULL – umożliwia wysyłanie zapytań dotyczących obiektów z atrybutem niezdefiniowanej wartości właściwości. Klasycznym przykładem jest wysyłanie zapytań o parametr pierwiastek AdUnit, wysyłając zapytanie o AdUnit o wartości null identyfikator nadrzędny.

    Przykład: WHERE parentId IS NULL.

  • <bind variable> – możesz użyć usługi Value obiektów zamiast wpisanego na stałe elementu <value> w zapytaniu PQL. Powiązanie jest wskazywana w PQL za pomocą nazwy ciągu znaków bez spacji, zaczynając dwukropkiem.

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

    // 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 zmiennej bind lub używając ciągu tekstowego sformatowanego zgodnie z 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);

Pobieram tabele odpowiedników z PQL

Tabele odpowiedników zapewniają mechanizm wyszukiwania nieprzetworzonych wartości zawartych w plikach przesyłania danych, co umożliwia dopasowywanie informacji o wyświetlaniu reklam (np. jednostki reklamowej lub elementu zamówienia) do wstępnie przypisanych wartości przechowywanych w bazie danych.

Jeśli raporty są generowane za pomocą usługi ReportService lub raportów usługi Przenoszenie danych, możesz uzupełnić dane raportu o dodatkowe pola. Na przykład w raporcie z wymiarem LINE_ITEM_ID. lub ze zdarzeniem przenoszenia danych, które ma pole LineItemId, możesz utworzyć tabelę odpowiedników, która zawiera datę rozpoczęcia każdego elementu zamówienia, datę zakończenia, typ, stan i inne przydatne atrybuty.

Istnieje kilka sposobów realizacji tej funkcji dopasowania:

  1. Użyj przygotowanych przez nas tabel odpowiedników BigQuery Data Transfer Service. Pamiętaj, że te tabele dopasowania nie zawierają wszystkich pól elementów.
  2. Skuteczną metodą jest użycie dowolnej z dostępnych w języku angielskim usługi PublisherQueryLanguageService .
  3. Jeśli dla elementu nie ma tabeli BigQuery ani PQL albo w tabeli brakuje wymaganych pól, możesz to zrobić bezpośrednio z usługi encji, na przykład OrderService.

Python

Konfigurowanie zapytania o raport

Zacznij od utworzenia zadania raportu i określ parametry raportu, takie jak wymiarów, kolumn i zakresu 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='v202508')

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)

Pobieranie danych z tabeli PQL Line_Item

Aby dopasować raport do dodatkowych danych elementów zamówienia, możesz użyć parametru Line_Item Tabela PQL.

# 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 elementu zamówienia

W tym przykładzie użyto parametru pandas ponieważ znacznie ułatwia pracę z danymi w postaci tabeli. W tym przypadku służy do złączania danych raportu z danymi PQL w celu utworzenia tabeli dopasowania.

# 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 GitHubie
.