Ad Manager SOAP API에서 이전

Ad Manager SOAP API는 Ad Manager 데이터를 읽고 쓰고 보고서를 실행하기 위한 기존 API입니다. 마이그레이션할 수 있는 경우 Ad Manager API (베타)를 사용하는 것이 좋습니다. 하지만 Ad Manager SOAP API 버전은 일반적인 수명 주기에 대해 지원됩니다. 자세한 내용은 Ad Manager SOAP API 지원 중단 일정을 참고하세요.

다음 가이드에서는 Ad Manager SOAP API와 Ad Manager API (베타)의 차이점을 간략히 설명합니다.

알아보기

표준 Ad Manager SOAP API 서비스 메서드에는 Ad Manager API에 상응하는 개념이 있습니다. Ad Manager API에는 단일 항목을 읽는 메서드도 있습니다. 다음 표는 Order 메서드의 매핑 예를 보여줍니다.

SOAP 메서드 REST 메서드
getOrdersByStatement networks.orders.get
networks.orders.list

인증

Ad Manager API (베타)로 인증하려면 기존 Ad Manager SOAP API 사용자 인증 정보를 사용하거나 새 사용자 인증 정보를 만들 수 있습니다. 두 옵션 중 어느 쪽을 사용하든 먼저 Google Cloud 프로젝트에서 Ad Manager API를 사용 설정해야 합니다. 자세한 내용은 인증을 참고하세요.

클라이언트 라이브러리를 사용하는 경우 환경 변수 GOOGLE_APPLICATION_CREDENTIALS를 서비스 계정 키 파일의 경로로 설정하여 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 애플리케이션 기본 사용자 인증 정보의 작동 방식을 참고하세요.

설치된 애플리케이션 사용자 인증 정보를 사용하는 경우 다음 형식의 JSON 파일을 만들고 대신 환경 변수를 경로로 설정합니다.

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN",
  "type": "authorized_user"
}

다음 값을 바꿉니다.

  • CLIENT_ID: 새 또는 기존 클라이언트 ID입니다.
  • CLIENT_SECRET: 새 또는 기존 고객 비밀입니다.

  • REFRESH_TOKEN: 새 또는 기존 새로고침 토큰입니다.

Linux 또는 macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

필터 차이점 이해하기

Ad Manager API (베타) 쿼리 언어는 모든 게시자 쿼리 언어(PQL) 기능을 지원하지만 상당한 구문 차이가 있습니다.

Order 객체를 나열하는 이 예에서는 바인딩 변수 삭제, 대소문자 구분 연산자, ORDER BY 및 LIMIT 절을 별도의 필드로 대체하는 등의 주요 변경사항을 보여줍니다.

Ad Manager SOAP API 

<filterStatement>
  <query>WHERE name like "PG_%" and lastModifiedDateTime &gt;= :lastModifiedDateTime ORDER BY id ASC LIMIT 500</query>
  <values>
    <key>lastModifiedDateTime</key>
    <value xmlns:ns2="https://www.google.com/apis/ads/publisher/v202502" xsi:type="ns2:DateTimeValue">
      <value>
        <date>
          <year>2024</year>
          <month>1</month>
          <day>1</day>
        </date>
        <hour>0</hour>
        <minute>0</minute>
        <second>0</second>
        <timeZoneId>America/New_York</timeZoneId>
      </value>
    </value>
  </values>
</filterStatement>

Ad Manager API (베타)

JSON 형식

{
  "filter": "displayName = \"PG_*\" AND updateTime > \"2024-01-01T00:00:00-5:00\"",
  "pageSize": 500,
  "orderBy":  "name"
}

URL 인코딩

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

Ad Manager API (베타)는 모든 PQL 기능을 지원하며, Ad Manager SOAP API와 다음과 같은 문법 차이가 있습니다.

  • AND 및 OR 연산자는 Ad Manager API (베타)에서 대소문자를 구분합니다. 소문자 and 및 or는 필드 전체를 검색하는 Ad Manager API (베타)의 기능인 리터럴 검색 문자열로 간주됩니다.

    대문자 연산자 사용

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false

    소문자가 리터럴로 처리됨

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'
// and any field in the order has the literal value 'and'.
notes = "lorem ipsum" and archived = false

  • * 문자는 문자열 일치의 와일드 카드입니다. Ad Manager API (베타)는 like 연산자를 지원하지 않습니다.

    Ad Manager SOAP API PQL

    // Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"

    Ad Manager API (베타)

    // Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"

  • 필드 이름은 비교 연산자의 왼쪽에 표시되어야 합니다.

    유효한 필터

    updateTime > "2024-01-01T00:00:00Z"

    잘못된 필터

    "2024-01-01T00:00:00Z" < updateTime

  • Ad Manager API (베타)는 바인딩 변수를 지원하지 않습니다. 모든 값은 인라인 처리되어야 합니다.

  • 공백이 포함된 문자열 리터럴은 큰따옴표로 묶어야 합니다(예: "Foo bar"). 작은따옴표를 사용하여 문자열 리터럴을 래핑할 수는 없습니다.

순서 지정 절 삭제

Ad Manager API (베타)에서는 정렬 순서를 지정하는 것이 선택사항입니다. 결과 집합의 정렬 순서를 지정하려면 PQL ORDER BY 절을 삭제하고 대신 orderBy 필드를 설정합니다.

GET networks/${NETWORK_CODE}/orders?orderBy=updateTime+desc

오프셋에서 페이지로 나누기 토큰으로 이전

Ad Manager API (베타)는 대규모 결과 집합을 페이지로 나누는 데 LIMIT 및 OFFSET 절 대신 페이지 링크 토큰을 사용합니다.

Ad Manager API (베타)는 pageSize 매개변수를 사용하여 페이지 크기를 제어합니다. Ad Manager SOAP API의 LIMIT 절과 달리 페이지 크기를 생략하면 전체 결과 세트가 반환되지 않습니다. 대신 list 메서드는 기본 페이지 크기 50를 사용합니다. 다음 예에서는 pageSize 및 pageToken를 URL 매개변수로 설정합니다.

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

Ad Manager SOAP API와 달리 Ad Manager API (베타)는 페이지가 추가되더라도 요청된 페이지 크기보다 적은 결과를 반환할 수 있습니다. nextPageToken 필드를 사용하여 추가 결과가 있는지 확인합니다.

페이징에는 오프셋이 필요하지 않지만 멀티스레딩에는 skip 필드를 사용할 수 있습니다. 멀티스레딩을 사용하는 경우 첫 번째 페이지의 페이지로 나누기 토큰을 사용하여 동일한 결과 집합에서 읽고 있는지 확인합니다.

# First thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

# Second thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}&skip=50