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

Składnia i użycie PQL

PQL to podobny język SQL do wysyłania zapytań dotyczących obiektów. Składnia PQL: podobny do SQL, z pewnymi różnicami opisanymi 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.
  • W przypadku ciągów znaków zmiany znaczenia są stosowane automatycznie, gdy są używane w parametrach powiązania. 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 wyrażeniami AND i OR. Wyrażenia I i LUB są łączone w grupy, w nawiasach. Wykonuję zapytanie "" (puste) string), 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 musi być powiązany tylko jeden z nich muszą być prawdziwe. Aby sprawdzić którąś z kilku wartości dla jednej możesz użyć klauzuli IN.

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

  • AND – łączy wiele warunków, które muszą zostać 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 kierunek jest inny jest określony, domyślna wartość to ASC. Jeśli nie występuje ta klauzula domyślna wartość to ASC w pierwszym polu.

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

  • LIMIT – liczba wyników do zwrócenia. LIMIT może również zawierać element <offset>, który jest o ile wierszy od początku chcesz przesunąć w zbiorze wyników.

    Przykłady (oba przykłady zwracają taki sam zestaw wyników):

    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50 WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET – przesunięcie w zestawie wyników. zwracających 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ć, obejmują 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ć ujęte w cudzysłów lub nie. Symbole wieloznaczne nie są obsługiwane.
  • IN – porównuje wartość właściwości z każdym elementem w kolumnie lista; jeśli któraś z nich jest zgodna, jest to dopasowanie dodatnie. IN jest odpowiednikiem wielu zapytań =, po jednym dla każdej wartości, połączonych operatorem LUB. Wartości podaje się w postaci listy rozdzielanej przecinkami ujęte w nawiasy: (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 podaje się w postaci listy rozdzielanej przecinkami ujęte w nawiasy: (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 procentu (%) oznacza zero, jeden lub 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 według przypisując wartość DateTime do zmiennej powiązania lub za pomocą funkcji w formacie zgodnym 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);

Pobieram tabele odpowiedników z PQL

Tabele odpowiedników udostępniają mechanizm wyszukiwania nieprzetworzonych wartości zawartych w plików przenoszenia danych, które pozwalają dopasować informacje o wyświetlaniu reklam (np. jednostki lub elementu zamówienia) do wstępnie przypisanych wartości przechowywanych w bazie danych.

Jeśli generujesz raporty za pomocą usługi ReportService lub dzięki Przenoszeniu danych , możesz uzupełnić dane do raportu o dodatkowe . 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 wykonania tej funkcji:

  1. Użyj przygotowanych przez nas tabel odpowiedników BigQuery Data Transfer Service. Pamiętaj, że te tabele odpowiedników nie zawierają wszystkich pól elementu.
  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='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)

Pobierz dane z tabeli PQL elementu zamówienia

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)

Połącz dane 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 , aby połączyć dane 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 GitHubie