제품에 관해 논의하고 의견을 제공하려면 Google 광고 및 측정 커뮤니티 서버의 공식 Ad Manager Discord 채널에 참여하세요.

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와 다음과 같은 구문 차이가 있습니다.

Ad Manager API (베타)에서 AND 및 OR 연산자는 대소문자를 구분합니다. 소문자 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"). 문자열 리터럴을 묶는 데 작은따옴표를 사용할 수 없습니다.

order by 절 삭제

정렬 순서 지정은 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 절과 달리 페이지 크기를 생략해도 전체 결과 집합이 반환되지 않습니다. 대신 목록 메서드는 기본 페이지 크기 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

보고서 이전

SOAP API는 지원이 중단된 보고서 도구에서만 보고서를 읽고 실행할 수 있습니다. 반대로 REST API는 양방향 보고서만 읽고, 쓰고, 실행할 수 있습니다.

보고 도구와 API는 ID 공간이 다릅니다. SOAP API의 SavedQuery ID는 REST API에서 사용할 수 없습니다.

SavedQuery를 사용하는 경우 UI에서 보고서를 대화형 보고서로 이전하고 두 ID 공간 간에 매핑을 만들 수 있습니다. 보고서 이전에 대한 자세한 내용은 보고서를 양방향 보고서로 이전하기를 참고하세요.

API 차이점 이해

SOAP API와 REST API가 보고서 정의와 결과를 처리하는 방식에는 몇 가지 차이점이 있습니다.

보고서에서 NAME만 요청한 경우 SOAP API는 결과에 해당하는 ID 측정기준을 자동으로 추가했습니다. REST API에서는 결과에 포함되도록 ReportDefinition에 ID 측정기준을 명시적으로 추가해야 합니다.
SOAP API에는 측정항목의 명시적 유형이 없었습니다. REST API는 Dimension 열거형 값에 문서화된 데이터 유형을 정의합니다. ENUM 측정기준은 개방형 enum입니다. 결과를 파싱할 때 새 enum 값과 알 수 없는 enum 값을 처리해야 합니다.
SOAP API는 Dimensions와 DimensionAttributes을 분리했습니다. REST API에는 두 가지를 모두 포함하는 통합 Dimension enum이 있습니다.
SOAP API에는 측정기준 수에 제한이 없었습니다. 대화형 보고서에는 UI와 API 모두에서 10개의 측정기준 한도가 있습니다. 동일한 ID 공간으로 분류되는 측정기준은 단일 측정기준으로 집계됩니다. 예를 들어 ORDER_NAME, ORDER_ID, ORDER_START_DATE만 포함하는 경우 한도를 계산할 때 1개의 측정기준으로 간주됩니다.