게시자 쿼리 언어 (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 - 여러 조건을 조인하며 이 중 하나만 참이면 됩니다. 단일 속성에 대해 여러 값 중 하나라도 확인하려면 속성을 사용하려면 IN 절을 사용하는 것이 좋습니다.

    예: WHERE width = 728 OR height = 90

  • AND - 모두 충족되어야 하는 여러 조건을 조인합니다. 충족하도록 할 수 있습니다.

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

  • ORDER BY - 반환된 결과를 오름차순(ASC: 'A'가 먼저 표시됨) 또는 내림차순(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 연산자는 여러 = 쿼리(값당 하나씩)와 같습니다. 여러 개의 논리곱으로 이루어져 있습니다. 값은 쉼표로 구분된 값 목록으로 지정되며 괄호로 묶입니다(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 상위 ID가 있는 AdUnit를 쿼리하여 루트 AdUnit를 쿼리하는 것입니다.

    예: WHERE parentId IS NULL

  • <bind variable> - PQL 쿼리에서 하드코딩된 <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. 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='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)

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