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ğlantı parametrelerinde kullanıldığında otomatik olarak kod dışına alınır. Aksi halde:

    • Tek tırnak (kesme işareti) içindeki bir dize için tek tırnak işareti olarak yazarak ekleme yapabilirsiniz.

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

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

  • WHERE - Sıfır veya daha fazla koşuldan oluşan bir kümeyi ifade eder. isteğe bağlı olarak AND veya OR ifadeleri kullanılarak birleştirilebilir. VE ya da VEYA ifadelerini bir araya getirerek parantez içine alın. "" sorgusu yürütülüyor (boş) string), 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 biri). doğru ol. Tek bir öğe için birkaç değerden herhangi birini kontrol etmek istiyorsanız özelliğini kullanmak istiyorsanız IN ifadesini kullanabilirsiniz.

    Örnek: WHERE width = 728 OR height = 90

  • AND - Hepsi aynı olması gereken birden fazla koşulu birleştirir ifade eder.

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

  • ORDER BY - Döndürülen sonuçları şu iki biçimden birinde sıralar: artan ('A'nın ilk olduğu yerde ASC) veya azalan (DESC burada 'A' son sıradadır) sırası. Yön belirtildiğinde varsayılan olarak ASC değerine ayarlanır. Bu ifade eklenmezse ilk alanda varsayılan değer ASC değeridir.

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

  • LIMIT: Döndürülecek sonuçların sayısı. İlgili içeriği oluşturmak için kullanılan LIMIT, aynı zamanda bir <offset> de içerebilir. başlangıçtan itibaren sonuç kümenizin uzaklığı için kaç satır gerektiğini belirtir.

    Ö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ı görmek için bunu kullanın.

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

  • <property> - nesnesini tanımlayın. Her bir nesne, filtreleme için kullanabileceğiniz farklı özellikler sunar. PQL kullanarak; genellikle bir Search Ads 360'ın desteklediği tüm özelliklere nesnesi hakkında bilgi edinin. Hangi özelliklerin PQL sorgularını desteklediğini görmek için aşağıdaki listeyi kontrol edin. Ö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 listele: 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. bunları VEYA işlecini birlikte kullanmak gerekir. Değerler, değerlerin virgülle ayrılmış listesi olarak değerleri, parantez içinde: (a, b, c). Listedeki tüm değerler yardımcı olur.

    Ö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 birçok != sorgusuna eşdeğerdir. bunları VEYA işlecini birlikte kullanmak gerekir. Değerler, değerlerin virgülle ayrılmış listesi olarak değerleri, parantez içinde: (a, b, c). Listedeki tüm değerler yardımcı olur.

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

  • LIKE - Joker karakter kullanarak nesneleri sorgulamanızı sağlar dize eşleştirmeyi kullanabilirsiniz. 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 - Bir tanımlanmamış özellik değeri. Bunun klasik örneği, Null değeri olan bir AdUnit için sorgulayarak AdUnit kök AdUnit üst kimlik.

    Örnek: WHERE parentId IS NULL.

  • <bind variable> - Value kullanabilirsiniz sabit kodlu <value> yerine nesneler değerleri hakkında daha fazla bilgi edinin. Bağlama değişkeni boşluk içermeyen bir dize adı kullanılarak PQL'de çağrılır. : (iki nokta üst üste) ile değiştirin.

    Ö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ı getiriliyor

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.

Raporları ReportService veya Veri Aktarımı ile raporlarını ayarlamak için alanları. Ö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. Google Ads'in sağladığı önceden hazırlanmış eşleşme tablolarını BigQuery Veri Aktarım Hizmeti. 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='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)

Line_Item PQL tablosundan veri indir

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

# 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 kullanılmış PQL verileriyle birleştirerek eşleşme tablosu oluşturabilirsiniz.

# 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örüntüle