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

PQL 구문 및 사용법

PQL은 객체 쿼리를 위한 SQL과 유사한 언어입니다. PQL 구문은 SQL과 유사하지만 여기에 설명된 몇 가지 차이점이 있습니다. 이 섹션 에는 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>

참고

• PQL 키워드는 대소문자를 구분하지 않습니다.
• 문자열은 바인드 매개변수에 사용될 때 자동으로 이스케이프됩니다. 그렇지 않은 경우 다음 단계를 따르세요. <ph type="x-smartling-placeholder">
  </ph>

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

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

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

• WHERE - 0개 이상의 조건 집합을 표현합니다. 선택사항으로 AND 또는 OR 구문을 사용하여 조인됩니다. AND 또는 OR 구문을 번들로 묶을 수 있습니다. 괄호를 사용합니다. "" 쿼리 실행 (비어 있음) string)는 모든 항목을 반환합니다.

  예: 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 - 모두 충족되어야 하는 여러 조건을 조인합니다. 충족하도록 할 수 있습니다.

  예: 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 - 속성의 값을 다음의 각 항목과 비교합니다. list; 하나라도 일치하면 양의 일치입니다. 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 - 정의되지 않은 속성 값입니다. 대표적인 예로 null이 있는 AdUnit를 쿼리하여 AdUnit 루트 상위 ID를 지정합니다.

  예: WHERE parentId IS NULL

• <bind variable> - Value를 사용할 수 있습니다. 객체를 하드 코딩 <value> 대신 값을 추출할 수 있습니다 바인드 변수는 공백 없는 문자열 이름을 사용하여 PQL에서 참조되며 : (콜론)으로 대체합니다.

  예 (쿼리를 만들고 하드 코딩된 id 및 status 속성 값):

  // 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. 사전 제작된 데이터 이동 색인은 <ph type="x-smartling-placeholder"></ph> BigQuery Data Transfer Service를 사용해 보세요. 이러한 데이터 이동 색인에 모든 항목 필드가 포함되지는 않습니다.
2. 한 가지 효율적인 방법은 사용 가능한 PublisherQueryLanguageService 표를 참조하세요.
3. 항목에 대한 BigQuery 또는 PQL 테이블이 없거나 테이블에 필요한 필드가 누락된 경우 항목의 서비스에 직접 연결할 수 있습니다(예: OrderService).

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

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

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