버전 관리

Ad Manager API에는 명명된 주요 버전 출시와 현재 주요 버전과 하위 호환되는 인플레이스 출시가 모두 있습니다.

서비스, 메서드, 필드는 메이저 버전 (예: v1) 내에서 언제든지 지원 중단으로 표시될 수 있지만 해당 메이저 버전이 지원 중단될 때까지는 계속 지원됩니다.

주 버전 출시

주 버전 출시는 하위 호환되지 않는 API 변경사항이 있는 출시로 정의됩니다. 이러한 출시에는 이름이 지정되고 API 엔드포인트가 다릅니다. 이전 주요 버전은 마이그레이션 기간 동안 지원됩니다.

Ad Manager API에는 주요 버전의 정기 출시 주기가 없습니다. 새로운 메이저 버전은 필요한 경우에만 출시됩니다.

인플레이스 출시

새로운 기능과 버그 수정을 포함한 하위 호환 변경사항은 현재 주 API 버전에 인플레이스로 출시됩니다. 클라이언트는 API 응답에서 알 수 없는 필드를 처리해야 합니다.

이전 버전과의 호환성

하위 호환성은 메이저 버전 내의 변경사항에 대해 유지됩니다. 호환성은 다음과 같이 정의됩니다.

  1. 소스 호환성: 이전 버전에 대해 작성된 코드가 최신 버전에 대해 컴파일되고 최신 버전의 클라이언트 라이브러리로 성공적으로 실행됩니다.

  2. 통신 호환성: 이전 버전에서 작성된 코드가 최신 서버와 올바르게 통신합니다. 즉, 입력과 출력이 호환될 뿐만 아니라 직렬화 및 역직렬화 기대치가 계속 일치합니다.

  3. 시맨틱 호환성: 이전 버전을 대상으로 작성된 코드는 대부분의 합리적인 개발자가 예상하는 결과를 계속 받습니다.

다음 표에는 API 변경사항의 유형과 하위 호환성이 고려되는지 여부가 나와 있습니다.

서비스

변경 유형 하위 호환
새 서비스 추가 예
서비스 삭제 아니요

메서드

변경 유형 하위 호환
새 메서드 추가 예
메서드 삭제 아니요
메서드의 요청 또는 응답 유형 변경 아니요

사물

변경 유형 하위 호환
필수 입력란 추가 아니요
선택사항 필드 추가 예
필드를 하위 메시지 안팎으로 이동 아니요
필드를 필수에서 선택사항으로 변경 예
필드를 선택사항에서 필수사항으로 변경 아니요
변경 불가능한 제한 삭제 예
변경 불가능한 제한 추가 아니요

열거

변경 유형 하위 호환
enum 값 추가 예
enum 값 삭제 아니요

지원 중단된 필드 동작

대체 필드

대체 항목이 있는 필드의 경우 가능한 경우 두 필드가 모두 채워집니다. 업데이트할 때는 두 필드 중 하나를 설정할 수 있습니다. 업데이트 요청에 두 필드를 모두 포함하면 INVALID_ARGUMENT 오류가 발생합니다.

다음 스키마를 고려해 보세요.

{
  // The cost of this Foo in micros.
  // Deprecated: Use `cost` instead.
  "costMicros": number,

  // The cost of this Foo.
  "cost": {
    object (Money)
  }
}

읽기 응답은 두 필드를 모두 동일한 값으로 채웁니다.

{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 250000000
  }
}

업데이트 요청은 두 값 중 하나를 설정할 수 있습니다. 두 필드를 모두 포함하면 INVALID_ARGUMENT 오류가 발생합니다.

costMicros 

// Update payload
{
  "costMicros": 1500000
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

비용 

// Update payload
{
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

둘 다 

// Update payload
{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "costMicros",
            "description": "Cannot update both costMicros and cost."
          }
        ]
      }
    ]
  }
}

지원 중단된 기능

제품 기능이 지원 중단되면 해당 필드가 지원 중단된 것으로 표시되며 의미상 적절한 기본값이 반환될 수 있습니다. 업데이트는 무시할 수 있습니다.

{
  // The salesperson split amount in micros.
  // Deprecated: The Sales Management feature has been deprecated. This field
  // will always be `0`.
  "salespersonSplitMicros": number,
}