Yayıncı Sorgu Dili (PQL) Geliştirici Kılavuzu

PQL söz dizimi ve kullanımı

PQL, nesneleri sorgulamak için SQL benzeri bir dildir. PQL söz dizimi SQL'inkine benzerdir ancak burada açıklanan birkaç farklılık vardır. Bu bölümde, PQL söz dizimi ve bunun çeşitli nesne türlerini filtrelemek için nasıl kullanılacağı açıklanmaktadır.

PQL söz dizimi şu şekilde özetlenebilir:

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

Notlar

  • PQL anahtar kelimeleri büyük/küçük harfe duyarlı değildir.
  • Bağlama parametrelerinde kullanıldığında dizelerden otomatik olarak çıkış yapılır. Aksi halde:
    • Tek tırnak (kesme işareti) içindeki dizelerde ek kesme işaretini tek tırnak çift olarak yazarak ayırın.

      Örnek: "WHERE name = 'Company''s name'"

Anahtar kelimeler (büyük/küçük harfe duyarlı değil)

  • WHERE - İsteğe bağlı olarak VE ya da VEYA ifadeleri kullanılarak birleştirilen, sıfır veya daha fazla koşul kümesini ifade eder. VE ya da VEYA ifadelerini parantez içinde gruplandırabilirsiniz. "" sorgusunun (boş dize) çalıştırılması her şeyi döndürür.

    Örnekler: WHERE width = 728
    WHERE width = 728 AND height = 90
    WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)

  • OR: Birden çok koşulu birleştirir. Yalnızca birinin doğru olması gerekir. Tek bir tesisteki çeşitli değerlerden herhangi birini kontrol etmek istiyorsanız IN ifadesini kullanabilirsiniz.

    Örnek: WHERE width = 728 OR height = 90

  • AND - VE ifadesi kullanılarak karşılanması gereken birden çok koşulu birleştirir.

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

  • ORDER BY - Döndürülen sonuçları artan (ASC burada "A"nın başında gelir) veya azalan (DESC burada "A"nın son olduğu) düzende sıralar. Yön belirtilmezse varsayılan olarak ASC değeri kullanılır. Bu ifade dahil edilmezse birinci alanda varsayılan ASC değeri olur.

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

  • LIMIT - Döndürülecek sonuç sayısı. LIMIT, sonuç kümenizin başlangıcından ofsetine kadar kaç satır olduğunu belirten bir <offset> de içerebilir.

    Örnekler (her iki örnek de aynı sonuç kümesini döndürür):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
    WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET - Değer döndürmeye başlamak için sonuç kümesine eklenen ofset. Sonuçlar arasında gezinmek için bunu kullanın.

    Örnek (51-100 arası sonuçları döndürür):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.

  • <property> - Nesne tarafından gösterilen özelliklerden biri. Her nesne, PQL kullanarak filtreleyebileceğiniz farklı özellikleri gösterir. Genellikle bir nesne tarafından desteklenen tüm özelliklerde filtreleme yapamazsınız. Bu nedenle, hangi özelliklerin PQL sorgularını desteklediğini görmek için aşağıdaki listeyi kontrol edin. Örneğin, filtreleyebileceğiniz reklam öğesi özellikleri arasında id, name, width ve height yer alır.
  • <value> - Dize değerleri tek (') tırnak işaretiyle tırnak içine alınmalıdır. Sayı değerleri tırnak içine alınmış veya tırnak içine alınmış olabilir. Joker karakterler desteklenmez.
  • IN - Bir tesisin değerini listedeki her bir öğeyle karşılaştırır. Eşleşirse pozitif eşleşmedir. IN operatörü, birlikte VEYA uygulanan her değer için bir tane olacak şekilde birçok = sorgusuna eş değerdir. Değerler, parantez içine alınmış, virgülle ayrılmış değerler listesi olarak belirtilir: (a, b, c). Listedeki tüm değerler değerlendirilir.

    Örnek: WHERE name IN ('CompanyNameA', 'CompanyNameB')

  • NOT IN - Bir özelliğin değerini listedeki her bir öğeyle karşılaştırır. Eşleşme yoksa pozitif eşleşmedir. NOT IN operatörü, birlikte VEYA uygulanan her değer için bir tane olacak şekilde birçok != sorgusuna eş değerdir. Değerler, parantez içine alınmış, virgülle ayrılmış değerler listesi olarak belirtilir: (a, b, c). Listedeki tüm değerler değerlendirilir.

    Örnek: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

  • LIKE - Joker karakter dizesi eşleştirmeyi kullanarak nesneleri sorgulamanızı sağlar. Yüzde işareti (%) sıfır, bir veya birden çok karakteri temsil eder. Eşleşen arama dizesini içine almak üzere bir çift kullanın.

    Örnekler: WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL - Özellik değeri tanımlanmamış nesneleri sorgulamanızı sağlar. Bunun klasik örneği, boş bir üst kimliğe sahip bir AdUnit sorgulayarak kök AdUnit için sorgulama yapmaktır.

    Örnek: WHERE parentId IS NULL.

  • <bind variable> - PQL sorgunuzda sabit kodlanmış <value> değerleri yerine Value nesnelerini kullanabilirsiniz. Bağlama değişkenine, PQL'de : (iki nokta) ile başlayan ve boşluksuz bir dize adı kullanılarak atıfta bulunulur.

    Örnek (Bir sorgu oluşturur ve sabit kodlanmış id ve status özellik değerlerinin yerine iki değişken girer):

    // 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 alanları - Bir bağlama değişkenine DateTime değeri atayarak veya ISO 8601'e göre biçimlendirilmiş bir dize kullanarak tarihe ve saate göre filtreleme yapabilirsiniz.
    // 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);

PQL ile eşleşme tabloları getiriliyor

Eşleşme tabloları, veri aktarımı dosyalarında yer alan ham değerler için bir arama mekanizması sağlayarak reklam sunma bilgilerini (reklam birimi veya satır öğesi gibi) veritabanında depolanan önceden atanmış değerlerle eşleştirmenize imkan tanır.

ReportService veya Veri Aktarımı raporları aracılığıyla rapor çalıştırıyorsanız rapor verilerinizi ek alanlarla desteklemek isteyebilirsiniz. Örneğin, LINE_ITEM_ID boyutuna sahip bir rapor veya LineItemId alanına sahip bir veri aktarımı etkinliği içeren bir raporla her satır öğesinin başlangıç tarihi, bitiş tarihi, türü, durumu ve diğer yararlı özelliklerini içeren bir eşleşme tablosu oluşturabilirsiniz.

Bu eşleştirme işlevini gerçekleştirmenin birkaç yolu vardır:

  1. BigQuery Veri Aktarım Hizmeti tarafından sağlanan önceden oluşturulmuş eşleşme tablolarını kullanın. Bu eşleşme tablolarının her öğe alanını içermediğini unutmayın.
  2. Verimli bir yaklaşım, mevcut PublisherQueryLanguageService tablolarından herhangi birini kullanmaktır.
  3. Varlık için BigQuery veya PQL tablosu yoksa ya da tabloda ihtiyacınız olan alanlar eksikse doğrudan söz konusu varlığın hizmetini (ör. OrderService) kullanabilirsiniz.

Python

Rapor sorgusu ayarlama

Boyutlar, sütunlar ve tarih aralığı gibi rapor parametrelerinizi belirterek bir rapor işi oluşturarak başlayın.

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

Raporu indirin

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

Line_Item PQL tablosundan veri indir

Raporunuzu ek satır öğesi verileriyle eşleştirmek için Line_Item PQL tablosunu kullanabilirsiniz.

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

Rapor verilerini satır öğesi verileriyle birleştirme

Bu örnekte, tablo verileriyle çalışmayı çok daha kolay hale getirdiği için pandas kitaplığı kullanılmaktadır. Burada, eşleşme tablosu oluşturmak amacıyla rapor verilerini PQL verileriyle birleştirmek için kullanılır.

# 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)
GitHub'da göster