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>

Lưu ý quan trọng: ReportService chỉ hỗ trợ một số cú pháp PQL. Xem phần 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:

  • Đố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ừ 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, kết hợp tuỳ ý 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 có dấu ngoặc đơn. Thực thi truy vấn "" (trống string) 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, chỉ một trong số đó phải là sự thật. 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 phải là tất cả hài lò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 điều khoản này không được bao gồm giá trị mặc định 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ề. Chiến lược phát hành đĩa đơn LIMIT cũng có thể bao gồm <offset>, là số hàng tính từ đầu để bù trừ cho tập hợ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 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 cho thấy các thuộc tính khác nhau mà bạn có thể lọc theo, sử dụng PQL; Bạn thường không thể lọc trên tất cả các cơ sở lưu trú được hỗ trợ bởi , vì vậy, hãy kiểm tra danh sách dưới đây để xem thuộc tính nào hỗ trợ truy vấn PQL. Ví dụ: thuộc tính của mẫu quảng cáo bạn có thể lọc theo id, name, width và height.
• <value> – Các giá trị chuỗi phải được đặt trong cặp dấu ngoặc kép dấu ngoặc đơ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. Ký tự đại diện không được hỗ trợ.
• IN – So sánh giá trị của một thuộc tính với từng mục trong một danh sách; nếu có kết quả trùng khớp thì kết quả là một kết quả khẳng định. 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 đượ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 đượ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 NOT name IN ('CompanyNameA', 'CompanyNameB')

• LIKE – Cho phép bạn truy vấn đối tượng bằng ký tự đại diện so khớp chuỗi. 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ụ điển hình cho việc này là truy vấn AdUnit gốc bằng cách truy vấn AdUnit có giá trị rỗng mã nhận dạng gốc.

  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 bằng 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ờ theo gán giá trị DateTime cho một biến liên kết hoặc bằng cách sử dụng 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ị hoặc mục hàng) thành các giá trị 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 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 của mỗi mục hàng, 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ó 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 tạo sẵn do Dịch vụ chuyển dữ liệu của BigQuery. 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ể thử thực thể đó 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 của bạn 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='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)

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

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

# 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 gấu trúc vì nó giúp 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