Bid Manager API v1.1에서 v2로 이전

2022년 3월에 Bid Manager API의 버전 2가 출시되었습니다. 이 새 버전이 출시됨에 따라 곧 v1.1의 지원 종료 날짜를 발표할 예정입니다. 가능한 한 빨리 v1.1에서 v2로 마이그레이션을 시작하는 것이 좋습니다.

애플리케이션 마이그레이션

v1.1에서 v2로 이전하려면 v2를 호출하도록 엔드포인트 URL을 업데이트하고 중요 변경사항을 고려하도록 애플리케이션을 업데이트해야 합니다.

v1.1에서 v2로 API 호출 업데이트

v1.1 대신 v2를 사용하려면 새 v2 엔드포인트를 사용하도록 요청을 업데이트해야 합니다.

동등한 메서드 식별

v1.1을 사용하는 API 호출을 v2로 업데이트하려면 먼저 v2에서 이에 상응하는 v1.1 메서드를 식별해야 합니다.

v1.1과 v2 사이에 모든 서비스와 메서드의 다음 이름이 약간 변경되었습니다.

• v1.1의 서비스 Queries 및 Reports은 v2에서 queries 및 queries.reports로 알려져 있습니다.
• v2에서 메서드 이름이 다음과 같이 변경되었습니다.

  v1.1 메서드 이름	동등한 v2 메서드
  Queries.createquery	queries.create
  Queries.deletequery	queries.delete
  Queries.getquery	queries.get
  Queries.listqueries	queries.list
  Queries.runquery	queries.run
  Reports.listreports	queries.reports.list

새 엔드포인트로 업데이트

동등한 메서드를 확인한 후 요청을 업데이트해야 합니다. 예를 들어 v1.1로 queries.getquery 메서드를 호출하려면 다음 URL을 사용합니다.

https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId

queries.get이라고 하는 v2의 해당 메서드를 호출하려면 URL을 다음과 같이 업데이트하세요.

GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId

클라이언트 라이브러리를 사용하여 API에 요청하는 경우 최신 버전의 클라이언트 라이브러리를 사용하고 v2를 사용하도록 구성을 업데이트하세요.

필수 변경사항 적용

v2에는 여러 가지 브레이킹 체인지가 도입됩니다. 다음 안내를 검토하고 기존 Bid Manager API 사용과 관련된 필요한 변경사항을 적용하세요.

queries 서비스 호출 업데이트

• 원래 일반 중첩 객체로 표시된 Query 리소스의 다음 필드가 다음 객체 유형을 사용하도록 변경되었습니다.

  v1.1 필드	상응하는 v2 객체 유형
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	삭제됨
  params.options.pathQueryOptions.channelGrouping	삭제됨
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	삭제됨
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	삭제됨
  schedule	QuerySchedule

• 원래 일반 목록 객체로 표시된 Query 리소스의 다음 필드가 다음 새 객체 유형의 목록으로 변경되었습니다.

  v1.1 목록 필드	v2 객체 유형
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	삭제됨
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	삭제됨
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	삭제됨
  params.options.pathQueryOptions.pathFilters[]	삭제됨
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	삭제됨

• 원래 문자열로 표시된 Query 리소스의 다음 필드는 v2에서 enum 유형으로 표시되며 다음 변경사항이 포함됩니다.
  • 이제 metadata.dataRange의 v2 버전에서 Range enum을 사용합니다. 이 열거형으로 변환할 때 PREVIOUS_HALF_MONTH 값이 삭제되고 TYPE_NOT_SUPPORTED 값이 RANGE_UNSPECIFIED로 변경되었습니다.
  • 이제 metadata.format에서 Format enum을 사용합니다. 이 열거형으로 변환할 때 EXCEL_CSV 값이 삭제되고 FORMAT_UNSPECIFIED 값이 추가되었습니다.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match 및 params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match이 이제 Match 열거형을 사용합니다.
  • 이제 params.options.pathQueryOptions.pathFilters[].pathMatchPosition에서 PathMatchPosition 열거형을 사용합니다. 이 열거형으로 변환할 때 PATH_MATCH_POSITION_UNSPECIFIED 값이 추가되었습니다.
  • 이제 schedule.frequency에서 Frequency enum을 사용합니다. 이 열거형으로 변환할 때 FREQUENCY_UNSPECIFIED 값이 추가되었습니다.
  • 이제 params.type에서 ReportType enum을 사용합니다. 이 열거형으로 변환할 때 다음과 같이 변경되었습니다.
  • 다음 값은 지원 중단되었습니다.
    • TYPE_ACTIVE_GRP
    • TYPE_AUDIENCE_PERFORMANCE
    • TYPE_CLIENT_SAFE
    • TYPE_COMSCORE_VCE
    • TYPE_CROSS_FEE
    • TYPE_CROSS_PARTNER
    • TYPE_CROSS_PARTNER_THIRD_PARTY_DATA_PROVIDER
    • TYPE_ESTIMATED_CONVERSION
    • TYPE_FEE
    • TYPE_KEYWORD
    • TYPE_LINEAR_TV_SEARCH_LIFT
    • TYPE_NIELSEN_AUDIENCE_PROFILE
    • TYPE_NIELSEN_DAILY_REACH_BUILD
    • TYPE_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PAGE_CATEGORY
    • TYPE_PETRA_NIELSEN_DAILY_REACH_BUILD
    • TYPE_PETRA_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PIXEL_LOAD
    • TYPE_THIRD_PARTY_DATA_PROVIDER
    • TYPE_TRUEVIEW_IAR
    • TYPE_VERIFICATION
    • TYPE_YOUTUBE_VERTICAL
  • 나머지 값은 UI의 해당 값을 더 잘 반영하도록 모두 업데이트되었습니다.

    v1.1 값	상응하는 ReportType 값
    TYPE_NOT_SUPPORTED	REPORT_TYPE_UNSPECIFIED
    TYPE_GENERAL	STANDARD
    TYPE_INVENTORY_AVAILABILITY	INVENTORY_AVAILABILITY
    TYPE_AUDIENCE_COMPOSITION	AUDIENCE_COMPOSITION
    TYPE_ORDER_ID	FLOODLIGHT
    TYPE_TRUEVIEW	YOUTUBE
    TYPE_NIELSEN_SITE	GRP
    TYPE_PETRA_NIELSEN_AUDIENCE_PROFILE	YOUTUBE_PROGRAMMATIC_GUARANTEED
    TYPE_REACH_AND_FREQUENCY	REACH
    TYPE_REACH_AUDIENCE	UNIQUE_REACH_AUDIENCE
    TYPE_PATH	FULL_PATH
    TYPE_PATH_ATTRIBUTION	PATH_ATTRIBUTION

• metadata.dataRange, reportDataStartTimeMs, reportDataEndTimeMs 필드가 range, customStartDate, customEndDate 필드로 대체되었습니다. 새 날짜 필드는 Unix Epoch 이후의 경과 시간(밀리초) 대신 Date 객체를 사용합니다. 이러한 대체 필드는 QueryMetadata 객체의 dataRange 필드에 할당된 DataRange 객체로 이동되었습니다.
• QuerySchedule 객체에서 schedule.startTimeMs 및 schedule.endTimeMs 필드가 startDate 및 endDate 필드로 대체되었습니다. 새 날짜 필드는 Unix Epoch 이후의 경과 시간(밀리초) 대신 Date 객체를 사용합니다.
• metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport, metadata.latestReportRunTimeMs 필드가 삭제되었습니다. 쿼리의 가장 최근에 생성된 보고서에 관한 정보는 대신 queries.reports.list 메서드를 사용하여 검색해야 합니다. 이때 요청에서 가장 최근 보고서가 먼저 나열되도록 orderBy 쿼리 매개변수를 'key.reportId desc'로 설정합니다.
• kind, timezoneCode, metadata.locale, params.includeInviteData, schedule.nextRunMinuteOfDay 필드가 삭제되었습니다.
• queries.create은 생성 후 더 이상 자동으로 쿼리를 실행하지 않으며 asynchronous 쿼리 매개변수가 삭제되었습니다. queries.create 후에 queries.run를 호출하여 새 쿼리에 대한 보고서를 생성합니다.
• queries.run 메서드가 다음과 같이 업데이트되었습니다.
  • asynchronous 쿼리 매개변수가 synchronous 쿼리 매개변수로 대체되었습니다. 새 쿼리 매개변수는 역 논리로 작동하며 지정되지 않은 경우 false로 간주됩니다. 이를 고려할 때 queries.run는 v1.1의 기본값인 동기식과 달리 v2에서 기본적으로 비동기식으로 보고서를 생성합니다.
  • 요청 본문이 업데이트되어 timezoneCode 필드가 삭제되고 dataRange, reportDataStartTimeMs, reportDataEndTimeMs 필드가 dataRange 필드에 할당된 DataRange 객체로 대체되었습니다.
  • 이 메서드는 빈 응답 본문 대신 결과 Report 객체를 반환합니다.
• queries.list 응답 본문의 kind 필드가 삭제되었습니다.

reports 서비스 호출 업데이트

• Report 리소스의 다음 필드가 원래 일반 중첩 객체로 표시되었으며 다음 객체 유형을 사용하도록 변경되었습니다.

  v1.1 필드	상응하는 v2 객체 유형
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	삭제됨
  params.options.pathQueryOptions.channelGrouping	삭제됨
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	삭제됨
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	삭제됨

• 원래 일반 목록 객체로 표시된 Report 리소스의 다음 필드가 다음 새 객체 유형의 목록으로 변경되었습니다.

  v1.1 목록 필드	v2 객체 유형
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	삭제됨
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	삭제됨
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	삭제됨
  params.options.pathQueryOptions.pathFilters[]	삭제됨
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	삭제됨

• 원래 문자열로 표시된 Report 리소스의 다음 필드가 변경되어 v2의 해당 필드가 새 열거형 유형으로 표시되고 허용되는 값이 변경되었습니다.
  • 이제 metadata.status.format에서 Format enum을 사용합니다. 이 열거형으로 변환할 때 EXCEL_CSV 값이 삭제되고 FORMAT_UNSPECIFIED이 추가되었습니다.
  • 이제 metadata.status.state에서 State enum을 사용합니다. 이 enum으로 변환할 때 QUEUED 및 STATE_UNSPECIFIED 값이 추가되었습니다.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match 및 params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match이 이제 Match 열거형을 사용합니다.
  • 이제 params.options.pathQueryOptions.pathFilters[].pathMatchPosition에서 PathMatchPosition 열거형을 사용합니다. 이 열거형으로 변환할 때 PATH_MATCH_POSITION_UNSPECIFIED 값이 추가되었습니다.
  • 이제 params.type에서 ReportType enum을 사용합니다. 이 열거형으로 변환하는 과정에서 수많은 변경사항이 적용되었으며, 이러한 변경사항은 쿼리 서비스 호출 업데이트에 관한 이전 섹션에 자세히 나와 있습니다.
• ReportMetadata 객체에서 metadata.reportDataStartTimeMs 및 metadata.reportDataEndTimeMs 필드가 reportDataStartDate 및 reportDataEndDate 필드로 대체되었습니다. 새 필드는 Unix Epoch 이후의 경과 시간(밀리초) 대신 Date 객체를 사용합니다.
• metadata.status.finishTimeMs이 ReportStatus 객체의 finishTime 필드로 대체되었습니다. 이 새로운 시간 필드는 Unix Epoch 이후 밀리초 대신 RFC3339 UTC 'Zulu' 형식의 타임스탬프로 날짜와 시간을 나타냅니다.
• metadata.status.failure 및 params.includeInviteData 필드가 삭제되었습니다.
• reports.list 응답 본문의 kind 필드가 삭제되었습니다.

오류 처리 로직 업데이트

API 전반의 오류 메시지가 v2에서 업데이트되었습니다. 이러한 새로운 오류 메시지는 더 구체적이며, 경우에 따라 오류가 반환되는 원인이 되는 API 요청의 값에 관한 정보를 제공합니다. 기존 오류 처리 로직이 특정 오류 메시지 텍스트에 의존하는 경우 v2로 이전하기 전에 오류 처리를 일반화하세요.