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

PQL söz dizimi ve kullanımı

PQL, nesneleri sorgulamak için kullanılan SQL benzeri bir dildir. PQL söz dizimi: bu SQL'inkine benzer. Burada açıklanan bazı farklılıklar vardır. Bu bölüm , PQL söz dizimini ve çeşitli nesne türlerini filtrelemek için nasıl kullanılacağını açıklar.

PQL söz dizimi aşağıdaki gibi ö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.
  • Dizeler, bağlama parametrelerinde kullanıldığında otomatik olarak kaçılır. Aksi halde:

    • Tek tırnak işareti (tırnak) içinde bir dize için ek tırnak işaretlerini bir çift tek tırnak işareti olarak yazarak tırnak işaretinden kaçının.

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

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

  • WHERE: Dilerseniz VE veya VEYA ifadesi kullanılarak birleştirilmiş sıfır veya daha fazla koşulu ifade eder. VE veya VEYA ifade öbeklerini parantezle gruplandırabilirsiniz. "" (boş dize) sorgusunun yürütülmesi 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 fazla koşulu birleştirir (yalnızca biri). doğru ol. Tek bir mülk için birden fazla değerden herhangi birini kontrol etmek istiyorsanız IN yan tümcesi kullanmayı düşünebilirsiniz.

    Örnek: WHERE width = 728 OR height = 90

  • AND: VE maddesi kullanılarak tümünün karşılanması gereken birden fazla koşulu birleştirir.

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

  • ORDER BY: Döndürülen sonuçları artan (ASC; "A" ilk sıradadır) veya azalan (DESC; "A" son sıradadır) düzende sıralar. Yön belirtildiğinde varsayılan olarak ASC değerine ayarlanır. Bu yan tümce eklenmezse ilk alanda varsayılan değer ASC olur.

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

  • LIMIT: Döndürülecek sonuç sayısı. LIMIT, sonuç kümenizi dengelemek için başlangıçtan kaç satırın atlanacağını belirten bir <offset> da 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 - Başlangıcı olan sonuç grubuna ofset değer döndürmesini sağlar. Sonuçlar arasında gezinmek için bunu kullanın.

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

  • <property>: Nesnenin gösterdiği özelliklerden biri. Her nesne, PQL'yi kullanarak filtreleyebileceğiniz farklı özellikler gösterir. Genellikle bir nesne tarafından desteklenen tüm özellikleri filtreleyemezsiniz. Bu nedenle, hangi özelliklerin PQL sorgularını desteklediğini görmek için aşağıdaki listeyi inceleyin. Örneğin, filtreleyebileceğiniz reklam öğesi özellikleri şunlardır: id, name, width ve height.
  • <value> - Dize değerlerinin tırnak içine alınması gerekir: tek (') tırnak işareti. Sayı değerleri tırnak içine alınabilir veya tırnak içine alınabilir. Joker karakterler desteklenmez.
  • IN - Bir özelliğin değerini list; herhangi biri eşleşirse pozitif bir eşleşmedir. IN operatörü, her değer için bir tane olmak üzere birçok = sorgusuna eşdeğerdir. bu anahtar kelimeleri kullanabilirsiniz. Değerler, virgülle ayrılmış ve paranteze alınmış bir değer 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 her öğeyle karşılaştırır liste halinde belirtmelisiniz; hiçbiri eşleşmiyorsa pozitif bir eşlemedir. NOT IN operatörü, her değer için bir tane olmak üzere birlikte VEYA işlemi uygulanan birçok != sorgusuna eşdeğerdir. Değerler, değerlerin virgülle ayrılmış listesi olarak değerleri, parantez içinde: (a, b, c). Listedeki tüm değerler değerlendirilir.

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

  • LIKE: Joker karakter dize eşleştirmesini kullanarak nesneleri sorgulamanıza olanak tanır. Yüzde işareti (%) sıfır, bir veya birden fazla karakter kullanabilirsiniz. Eşleşen arama dizesini eklemek için bir çift kullanın.

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

  • IS NULL: Tanımlanmamış bir özellik değeri olan nesneleri sorgulamanıza olanak tanır. Bunun klasik örneği, boş bir üst kimliğe sahip bir AdUnit için sorgulayarak kök AdUnit için sorgulamadır.

    Örnek: WHERE parentId IS NULL.

  • <bind variable>: PQL sorgunuzda sabit kodlanmış <value> değerleri yerine Value <bind variable>öğelerini kullanabilirsiniz. PQL'de, bağlama değişkenine : (iki nokta üst üste) ile başlayan, boşluk içermeyen bir dize adı kullanılarak başvurulur.

    Örnek (Bir sorgu oluşturur ve yerine iki değişken girer: sabit kodlu id ve status özelliği değerleridir):

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

Eşleşme tabloları, Veri aktarım dosyalarını kullanarak reklam sunma bilgilerini (ör. reklam birimi veya satır öğesi) veritabanında depolanan önceden atanmış değerlere ekler.

ReportService aracılığıyla veya Veri Aktarımı raporlarıyla raporlar yayınlıyorsanız rapor verilerinizi ek alanlarla destekleyebilirsiniz. Örneğin, LINE_ITEM_ID boyutuna sahip bir raporla LineItemId alanına sahip bir veri aktarımı etkinliğiyle her satır öğesinin başlangıç tarihini içeren bir eşleşme tablosu oluşturabilirsiniz. bitiş tarihi, tür, durum ve diğer faydalı özellikleri ekleyin.

Bu eşleştirme işlevini yerine getirmenin birkaç yolu vardır:

  1. BigQuery Veri Aktarım Hizmeti tarafından sağlanan önceden hazırlanmış eşleşme tablolarını kullanın. Bu eşleşme tablolarının tüm öğe alanlarını içermediğini unutmayın.
  2. Mevcut PublisherQueryLanguageService tablolarını inceleyin.
  3. Varlık için BigQuery veya PQL tablosu yoksa ya da tabloda ihtiyacınız olan alanlar eksikse bu adımları uygulayabilirsiniz. OrderService gibi doğrudan tüzel kişi hizmetini kullanabilir.

Python

Rapor sorgusu oluşturma

Bir rapor işi oluşturup rapor parametrelerinizi belirterek başlayın: tarih aralığını seçin.

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

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

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 pandalar kitaplığına eklenmesine olanak tanır. Burada, eşleşme tablosu oluşturmak için rapor verilerini PQL verileriyle birleştirmek amacıyla 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