Pembuatan Versi

Ad Manager API memiliki rilis Versi utama bernama dan rilis langsung yang kompatibel dengan versi sebelumnya ke Versi utama saat ini.

Layanan, metode, dan kolom dapat ditandai sebagai tidak digunakan lagi kapan saja dalam Versi utama (misalnya v1), tetapi akan tetap didukung hingga Versi utama tersebut dihentikan.

Rilis versi utama

Rilis Versi utama ditentukan sebagai rilis dengan perubahan API yang tidak kompatibel dengan versi sebelumnya. Rilis ini akan diberi nama dan memiliki endpoint API yang berbeda. Versi Utama sebelumnya didukung untuk periode migrasi.

Ad Manager API tidak memiliki irama rilis reguler untuk Versi utama. Versi Utama baru hanya akan dirilis jika diperlukan.

Rilis langsung

Perubahan yang kompatibel dengan versi sebelumnya, termasuk fitur baru dan perbaikan bug, dirilis langsung ke Versi API Utama saat ini. Klien harus menangani kolom yang tidak diketahui dalam respons API.

Kompatibilitas Mundur

Kompatibilitas mundur dipertahankan untuk perubahan dalam Versi utama. Kompatibilitas ditentukan sebagai:

  1. Kompatibilitas sumber: Kode yang ditulis terhadap rilis sebelumnya dikompilasi terhadap rilis yang lebih baru, dan berhasil dijalankan dengan versi library klien yang lebih baru.

  2. Kompatibilitas kabel: Kode yang ditulis terhadap rilis sebelumnya berkomunikasi dengan benar dengan server yang lebih baru. Dengan kata lain, tidak hanya input dan output yang kompatibel, tetapi ekspektasi serialisasi dan deserialisasi terus cocok.

  3. Kompatibilitas semantik: Kode yang ditulis terhadap versi sebelumnya terus menerima apa yang diharapkan oleh sebagian besar developer yang wajar.

Tabel berikut mencantumkan jenis perubahan API dan apakah perubahan tersebut dianggap kompatibel dengan versi sebelumnya.

Layanan

Jenis Perubahan Kompatibel dengan versi sebelumnya
Menambahkan layanan baru Ya
Menghapus layanan Tidak

Metode

Jenis Perubahan Kompatibel dengan versi sebelumnya
Menambahkan metode baru Ya
Menghapus metode Tidak
Mengubah jenis permintaan atau respons metode Tidak

Objek

Jenis Perubahan Kompatibel dengan versi sebelumnya
Menambahkan kolom wajib Tidak
Menambahkan kolom opsional Ya
Memindahkan kolom ke dalam atau ke luar subpesan Tidak
Mengubah kolom dari wajib menjadi opsional Ya
Mengubah kolom dari opsional menjadi wajib Tidak
Menghapus batasan yang tidak dapat diubah Ya
Menambahkan batasan yang tidak dapat diubah Tidak

Enumerasi

Jenis Perubahan Kompatibel dengan versi sebelumnya
Menambahkan nilai enum Ya
Menghapus nilai enum Tidak

Perilaku kolom yang tidak digunakan lagi

Kolom pengganti

Untuk kolom yang memiliki pengganti, kedua kolom akan diisi jika memungkinkan. Saat memperbarui, salah satu kolom dapat ditetapkan. Menyertakan kedua kolom dalam permintaan pembaruan akan menghasilkan error INVALID_ARGUMENT.

Pertimbangkan skema berikut:

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

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

Respons baca akan mengisi kedua kolom dengan nilai yang setara:

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

Permintaan pembaruan dapat menetapkan salah satu nilai. Menyertakan kedua kolom akan menghasilkan error INVALID_ARGUMENT:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

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

biaya 

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

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

Keduanya 

// 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."
          }
        ]
      }
    ]
  }
}

Fitur yang dihentikan

Jika fitur produk dihentikan, kolom yang sesuai akan ditandai sebagai tidak digunakan lagi dan dapat menampilkan nilai default yang sesuai secara semantik. Pembaruan dapat diabaikan.

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