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 các đối tượng. Cú pháp PQL tương tự như cú pháp SQL, nhưng có một số điểm khác biệt như 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 nhiều loại đối tượng.

Có thể tóm tắt cú pháp PQL 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>

Lưu ý quan trọng: ReportService chỉ hỗ trợ một tập hợp con cú pháp PQL. Xem tài liệu về ReportQuery để biết thông tin chi tiết.

Ghi chú

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

  • Đối với một chuỗi 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 chuỗi dưới dạng một cặp dấu ngoặc đơn.

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

Từ khóa (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, tuỳ ý kết hợp bằng cách sử dụng cụm từ AND hoặc OR. Bạn có thể nhóm các cụm từ AND hoặc OR với dấu ngoặc đơn. Việc thực thi truy vấn "" (chuỗi trống) sẽ trả về mọi dữ liệu.

  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, chỉ một điều kiện trong số đó phải đúng. Nếu bạn muốn kiểm tra giá trị bất kỳ của một thuộc tính, 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 và 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 các kết quả được trả về theo thứ tự tăng dần (ASC trong đó "A" ở đầu) hoặc giảm dần (DESC trong đó "A" là cuối cùng). Nếu bạn không chỉ định hướng, giá trị mặc định sẽ là ASC. Nếu bạn không thêm mệnh đề này, thì giá trị mặc định sẽ là ASC trong trường đầu tiên.

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

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

  Ví dụ (cả hai ví dụ đều trả về cùng một nhóm 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 trả về các giá trị. Sử dụng công cụ này để xem qua các kết quả.

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

• <property> – Một trong các thuộc tính được đối tượng hiển thị. Mỗi đối tượng hiển thị các thuộc tính khác nhau mà bạn có thể lọc bằng PQL; thường thì bạn không thể lọc trên tất cả thuộc tính mà một đối tượng hỗ trợ. Vì vậy, hãy xem danh sách dưới đây để biết 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> – Các giá trị chuỗi phải được trích dẫn bằng một dấu ngoặc đơn ("). Bạn có thể trích dẫn hoặc không trích dẫn giá trị số. 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 danh sách; nếu có bất kỳ mục nào khớp thì đó là kết quả trùng khớp. 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 bằng toán tử OR. Các giá trị được chỉ định dưới dạng danh sách các giá trị được phân tách bằng dấu phẩy và đặt trong dấu ngoặc đơn: (a, b, c). Tất cả các giá trị trong danh sách đều được đá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ó mục nào khớp thì đó là kết quả trùng khớp. Toán tử NOT 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 bằng toán tử OR. Các giá trị được chỉ định dưới dạng danh sách các giá trị được phân tách bằng dấu phẩy và đặt trong dấu ngoặc đơn: (a, b, c). Tất cả các giá trị trong danh sách đều được đá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 tính năng so khớp chuỗi ký tự đại diện. Ký hiệu phần trăm (%) biểu thị số không, một hoặc nhiều ký tự. Sử dụng một cặp để bao gồm 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ụ điển hình là truy vấn AdUnit gốc bằng cách truy vấn AdUnit có mã nhận dạng mẹ rỗng.

  Ví dụ: WHERE parentId IS NULL.

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

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

  // 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 gán 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 so khớp cung cấp cơ chế tra cứu cho các giá trị thô có trong các 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ị chỉ định trước lưu trữ trong cơ sở dữ liệu.

Nếu đang chạy báo cáo thông qua ReportService hoặc báo cáo Chuyển dữ liệu, thì bạn nên bổ sung các trường bổ sung cho dữ liệu báo cáo. Ví dụ: với 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 bảng so khớp được 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 phương pháp hiệu quả là sử dụng bất kỳ bảng PublisherQueryLanguageService nào có sẵn.
3. Nếu thực thể đó không có bảng BigQuery hoặc PQL hoặc bảng thiếu các trường mà bạn cần, thì bạn có thể truy cập trực tiếp vào dịch vụ của thực thể đó, chẳng hạn như OrderService.

Python

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

Hãy 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ư thứ nguyê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='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)

Tải dữ liệu xuống từ bảng PQL của mục hàng

Để so khớp báo cáo 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 việc xử lý dữ liệu dạng bảng trở nên dễ dàng hơn nhiều. Ở đây, đối tượng 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