Hướng dẫn dành cho nhà phát triển về ngôn ngữ truy vấn của nhà xuất bản (PQL)

Cú pháp và cách sử dụng PQL

PQL là một ngôn ngữ giống như SQL để truy vấn đối tượng. Cú pháp PQL là tương tự như SQL, với một vài điểm khác biệt được mô tả ở đây. Phần này mô tả cú pháp PQL và cách sử dụng cú pháp này để lọc các loại đối tượng khác nhau.

Cú pháp PQL có thể được tóm tắt như sau:

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

Ghi chú

  • Từ khoá PQL không phân biệt chữ hoa chữ thường.
  • Chuỗi được thoát tự động khi được sử dụng trong các tham số liên kết. Nếu không:

    • Đối với một chuỗi nằm trong dấu nháy đơn (dấu nháy đơn), hãy thoát mọi dấu nháy đơn bổ sung bằng cách viết dưới dạng một cặp dấu nháy đơn.

      Ví dụ: "WHERE name = 'Company''s name'"

Từ khoá (không phân biệt chữ hoa chữ thường)

  • WHERE – Biểu thị một tập hợp không có hoặc nhiều điều kiện, kết hợp tuỳ ý bằng cách sử dụng cụm từ AND hoặc OR. Bạn có thể gói các cụm từ AND hoặc OR bằng dấu ngoặc đơn. Việc thực thi truy vấn "" (chuỗi trống) sẽ trả về mọi thứ.

    Ví dụ: WHERE width = 728
    WHERE width = 728 AND height = 90
    WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)

  • OR – Kết hợp nhiều điều kiện, trong đó chỉ một điều kiện phải đúng. Nếu bạn muốn kiểm tra bất kỳ giá trị nào trong số vài giá trị cho một hãy cân nhắc sử dụng mệnh đề IN.

    Ví dụ: WHERE width = 728 OR height = 90

  • AND – Kết hợp nhiều điều kiện mà tất cả đều phải được đáp ứng bằng cách sử dụng mệnh đề AND.

    Ví dụ: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB')

  • ORDER BY – Sắp xếp kết quả trả về theo một trong hai tăng dần (ASC trong đó "A" đứng đầu) hoặc giảm dần (DESC trong đó 'A' là đơn đặt hàng cuối cùng). Nếu hướng không phải đã chỉ định, giá trị mặc định sẽ là ASC. Nếu không có mệnh đề này, giá trị mặc định sẽ là ASC trên trường đầu tiên.

    Ví dụ: WHERE id IN (5008, 8745, 3487) ORDER BY id

  • LIMIT – Số kết quả cần trả về. LIMIT cũng có thể bao gồm <offset>, là số hàng từ đầu để bù cho tập kết quả của bạn.

    Ví dụ (cả hai ví dụ đều trả về cùng một tập kết quả):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
    WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET – Độ lệch trong tập hợp kết quả để bắt đầu giá trị trả về. Sử dụng nút này để xem qua các kết quả.

    Ví dụ (trả về kết quả từ 51 đến 100):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.

  • <property> – Một trong những cơ sở lưu trú mà . Mỗi đối tượng hiển thị các thuộc tính khác nhau mà bạn có th�� lọc theo, bằng cách sử dụng PQL; bạn thường không thể lọc theo tất cả các thuộc tính mà một đối tượng hỗ trợ, vì vậy, hãy kiểm tra danh sách bên dưới để xem những thuộc tính nào hỗ trợ truy vấn PQL. Ví dụ: các thuộc tính mẫu quảng cáo mà bạn có thể lọc theo bao gồm id, name, width và height.
  • <value> – Giá trị chuỗi phải được đặt trong dấu ngoặc kép đơn ('). Giá trị số có thể nằm trong cặp dấu ngoặc kép hoặc không trong dấu ngoặc kép. Không hỗ trợ ký tự đại diện.
  • IN – So sánh giá trị của một thuộc tính với từng mục trong một list; nếu có kết quả trùng khớp thì kết quả là một kết quả khẳng định. Toán tử IN tương đương với nhiều truy vấn =, mỗi truy vấn cho một giá trị, được kết hợp với nhau bằng toán tử HOẶC. Các giá trị được chỉ định dưới dạng danh sách được phân tách bằng dấu phẩy giá trị được đặt trong ngoặc đơn: (a, b, c). Tất cả giá trị trong danh sách là đánh giá.

    Ví dụ: WHERE name IN ('CompanyNameA', 'CompanyNameB')

  • NOT IN – So sánh giá trị của một thuộc tính với từng mục trong danh sách; nếu không có kết quả nào trùng khớp, thì kết quả là một kết quả dương. NOT IN tương đương với nhiều truy vấn !=, mỗi truy vấn cho một giá trị, được OR kết hợp. Các giá trị được chỉ định dưới dạng danh sách giá trị được phân tách bằng dấu phẩy, được đặt trong dấu ngoặc đơn: (a, b, c). Tất cả giá trị trong danh sách là đánh giá.

    Ví dụ: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

  • LIKE – Cho phép bạn truy vấn các đối tượng bằng cách so khớp chuỗi ký tự đại diện. Dấu phần trăm (%) biểu thị 0, 1 hoặc nhiều ký tự. Sử dụng một cặp để bao quanh chuỗi tìm kiếm đang được so khớp.

    Ví dụ: WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL – Cho phép bạn truy vấn các đối tượng có giá trị thuộc tính không xác định. Ví dụ cổ điển về điều này là truy vấn AdUnit gốc bằng cách truy vấn AdUnit có mã nhận dạng gốc rỗng.

    Ví dụ: WHERE parentId IS NULL.

  • <bind variable> – Bạn có thể sử dụng Value các đối tượng thay cho <value> được cố định giá trị trong mã trong truy vấn PQL của bạn. Ràng buộc A biến được tham chiếu trong PQL bằng cách sử dụng tên chuỗi không có dấu cách, bắt đầu với dấu : (dấu hai chấm).

    Ví dụ (Tạo một truy vấn và nhập hai biến thay cho thuộc tính id và status được cố định giá trị trong mã giá trị):

    // 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);
  • Trường DateTime – Bạn có thể lọc theo ngày và giờ bằng cách chỉ định giá trị DateTime cho một biến liên kết hoặc bằng cách sử dụng một chuỗi được định dạng theo 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);

Đang tìm nạp bảng so khớp bằng PQL

Bảng đối sánh cung cấp cơ chế tra cứu cho các giá trị thô có trong tệp chuyển dữ liệu, cho phép bạn so khớp thông tin phân phát quảng cáo (chẳng hạn như đơn vị quảng cáo hoặc mục hàng) với các giá trị được chỉ định trước được lưu trữ trong cơ sở dữ liệu.

Nếu bạn đang chạy báo cáo thông qua ReportService hoặc với tính năng Chuyển dữ liệu , bạn có thể muốn bổ sung cho dữ liệu báo cáo của mình các thông tin bổ sung mới. Ví dụ: với một báo cáo có phương diện LINE_ITEM_ID hoặc với một sự kiện chuyển dữ liệu có trường LineItemId, bạn có thể tạo một bảng so khớp bao gồm ngày bắt đầu, ngày kết thúc, loại, trạng thái và các thuộc tính hữu ích khác của từng mục hàng.

Có một số cách để thực hiện chức năng so khớp này:

  1. Sử dụng các bảng so khớp tạo sẵn do Dịch vụ chuyển dữ liệu của BigQuery cung cấp. Xin lưu ý rằng các bảng so khớp này không chứa mọi trường thực thể.
  2. Một cách tiếp cận hiệu quả là sử dụng bất kỳ PublisherQueryLanguageService nào có sẵn .
  3. Nếu thực thể không có bảng BigQuery hay PQL cho thực thể hoặc bảng đó thiếu các trường mà bạn cần, thì bạn có thể làm theo hướng dẫn đó của tổ chức đó, chẳng hạn như OrderService.

Python

Thiết lập truy vấn báo cáo

Bắt đầu bằng cách tạo một công việc báo cáo, chỉ định các thông số báo cáo như phương diện, cột và phạm vi ngày.

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

Tải báo cáo xuống

# Initialize a DataDownloader.
report_downloader = client.GetDataDownloader(version='v202505')

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)

Tải dữ liệu xuống từ bảng PQL của Line_Item

Để so khớp báo cáo của bạn với dữ liệu mục hàng bổ sung, bạn có thể sử dụng bảng PQL Line_Item.

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

Kết hợp dữ liệu báo cáo với dữ liệu mục hàng

Ví dụ này sử dụng thư viện pandas vì thư viện này giúp bạn làm việc với dữ liệu dạng bảng dễ dàng hơn nhiều. Ở đây, phương thức này được dùng để kết hợp dữ liệu báo cáo với dữ liệu PQL để tạo một bảng so khớp.

# 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)
 Xem trên GitHub