게시자 쿼리 언어 (PQL) 개발자 가이드

PQL 구문 및 사용법

PQL은 SQL과 유사한 객체 쿼리를 위한 언어입니다. PQL 구문은 SQL 구문과 비슷하지만 몇 가지 차이점이 여기에 설명되어 있습니다. 이 섹션에서는 PQL 구문 및 PQL 구문을 사용하여 다양한 객체 유형을 필터링하는 방법을 설명합니다.

PQL 구문은 다음과 같이 요약할 수 있습니다.

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

중요: ReportService는 PQL 구문의 하위 집합만 지원합니다. 자세한 내용은 ReportQuery 문서를 참고하세요.

Notes

• PQL 키워드는 대소문자를 구분하지 않습니다.
• 문자열은 바인드 매개변수에 사용될 때 자동으로 이스케이프 처리됩니다. 그렇지 않은 경우 다음 단계를 따릅니다.

  • 작은따옴표 안의 문자열 (아포스트로피)의 경우 추가 아포스트로피를 작은따옴표 쌍으로 작성하여 이스케이프 처리합니다.

    예: "WHERE name = 'Company''s name'"

키워드 (대소문자를 구분하지 않음)

• WHERE - 0개 이상의 조건 집합을 표현하며 선택적으로 AND 또는 OR 구문을 사용하여 결합합니다. AND 또는 OR 구문을 괄호로 묶을 수 있습니다. 쿼리 "" (빈 문자열)를 실행하면 모든 항목이 반환됩니다.

  예: WHERE width = 728
WHERE width = 728 AND height = 90
WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)

• OR - 여러 조건을 조인합니다. 이 중 하나만 true여야 합니다. 단일 속성의 여러 값을 검사하려면 IN 절을 사용하는 것이 좋습니다.

  예: WHERE width = 728 OR height = 90

• AND - AND 절을 사용하여 모두 충족해야 하는 여러 조건을 조인합니다.

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

• ORDER BY - 반환된 결과를 오름차순('A'가 첫 번째인 ASC) 또는 내림차순(DESC, 'A'가 마지막임)으로 정렬합니다. 방향을 지정하지 않으면 기본값은 ASC입니다. 이 절이 포함되지 않으면 첫 번째 필드의 기본값은 ASC입니다.

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

• LIMIT - 반환할 결과 수입니다. LIMIT에는 시작부터 결과 집합을 오프셋하는 행 수인 <offset>도 포함될 수 있습니다.

  예시 (두 예 모두 동일한 결과 집합을 반환함):
  WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
WHERE type = 'AGENCY' LIMIT 50,50

• OFFSET - 값 반환을 시작할 결과 집합의 오프셋입니다. 결과를 페이징할 때 사용합니다.

  예 (51~100개의 결과 반환):
  WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.

• <property> - 객체에 의해 노출된 속성 중 하나입니다. 각 객체는 PQL을 사용하여 필터링할 수 있는 다양한 속성을 제공합니다. 일반적으로 객체에서 지원하는 모든 속성을 필터링할 수는 없으므로 아래 목록을 확인하여 PQL 쿼리를 지원하는 속성을 확인하세요. 예를 들어 필터링 기준으로 사용할 수 있는 광고 소재 속성에는 id, name, width, height 등이 있습니다.
• <value> - 문자열 값은 작은따옴표로 묶어야 합니다. 숫자 값은 따옴표 또는 따옴표로 묶지 않을 수 있습니다. 와일드 카드는 지원되지 않습니다.
• IN - 속성 값을 목록의 각 항목과 비교합니다. 일치하는 항목이 있으면 긍정 일치입니다. IN 연산자는 여러 개의 = 쿼리(값별로 하나씩)가 OR로 연결된 것과 같습니다. 값은 괄호(a, b, c)로 묶이고 쉼표로 구분된 값 목록으로 지정됩니다. 목록의 모든 값이 평가됩니다.

  예: WHERE name IN ('CompanyNameA', 'CompanyNameB')

• NOT IN - 속성 값을 목록의 각 항목과 비교합니다. 일치하는 항목이 없으면 양수 일치입니다. NOT IN 연산자는 여러 개의 != 쿼리(값별로 하나씩)가 OR로 연결된 것과 같습니다. 값은 괄호(a, b, c)로 묶이고 쉼표로 구분된 값 목록으로 지정됩니다. 목록의 모든 값이 평가됩니다.

  예: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

• LIKE - 와일드 카드 문자열 일치를 사용하여 객체를 쿼리할 수 있습니다. 퍼센트 기호 (%)는 0개, 1개 또는 여러 개의 문자를 나타냅니다. 짝을 사용하여 일치시킬 검색 문자열을 묶습니다.

  예: WHERE name LIKE 'foo %searchString% bar'
WHERE name LIKE 'Aus%'

• IS NULL - 정의되지 않은 속성 값이 있는 객체를 쿼리할 수 있습니다. 이에 대한 전형적인 예는 상위 요소 ID가 null인 AdUnit를 쿼리하여 루트 AdUnit를 쿼리하는 것입니다.

  예: WHERE parentId IS NULL

• <bind variable> - PQL 쿼리에서 하드 코딩된 <value> 값 대신 Value 객체를 사용할 수 있습니다. 결합 변수는 PQL에서 공백 없이 문자열 이름을 사용하고 : (콜론)으로 시작합니다.

  예 (쿼리를 만들고 하드 코딩된 id 및 status 속성 값 대신 변수 2개 입력):

  // 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 필드 - DateTime 값을 결합 변수에 할당하거나 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);

PQL로 데이터 이동 색인 가져오기

데이터 이동 색인은 데이터 전송 파일 내에 포함된 원시 값에 대한 조회 메커니즘을 제공하므로 광고 게재 정보 (예: 광고 단위 또는 광고 항목)를 데이터베이스에 저장된 사전 할당 값과 일치시킬 수 있습니다.

ReportService 또는 데이터 전송 보고서를 통해 보고서를 실행하는 경우 추가 필드로 보고서 데이터를 보완해야 할 수 있습니다. 예를 들어 측정기준이 LINE_ITEM_ID인 보고서 또는 LineItemId 필드가 있는 데이터 전송 이벤트가 있는 경우 각 광고 항목의 시작일, 종료일, 유형, 상태 및 기타 유용한 속성이 포함된 데이터 이동 색인을 만들 수 있습니다.

다음과 같은 여러 가지 방법으로 이 일치 기능을 구현할 수 있습니다.

1. BigQuery Data Transfer Service에서 제공하는 미리 만들어진 데이터 이동 색인을 사용합니다. 이러한 데이터 이동 색인에 모든 항목 필드가 포함되는 것은 아닙니다.
2. 효율적인 방법은 사용 가능한 PublisherQueryLanguageService 테이블을 사용하는 것입니다.
3. 항목에 대한 BigQuery 또는 PQL 테이블이 없거나 테이블에 필요한 필드가 누락된 경우 OrderService와 같은 항목의 서비스를 직접 진행할 수 있습니다.

Python

보고서 검색어 설정

먼저 보고서 작업을 만들고 측정기준, 열, 기간과 같은 보고서 매개변수를 지정합니다.

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

보고서 다운로드

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

Line_Item PQL 표에서 데이터 다운로드

보고서를 추가 광고 항목 데이터와 일치시키려면 Line_Item 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)
    

보고서 데이터와 광고 항목 데이터 결합

이 예에서는 표 형식의 데이터를 훨씬 더 쉽게 사용할 수 있도록 Pandas 라이브러리를 사용합니다. 여기에서는 보고서 데이터를 PQL 데이터와 조인하여 데이터 이동 색인을 만드는 데 사용됩니다.

# 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에서 보기