Pembuatan Versi

Ad Manager REST API memiliki rilis versi Utama dan rilis di tempat yang kompatibel dengan versi sebelumnya ke versi Utama saat ini.

Layanan, metode, dan kolom dapat ditandai sebagai tidak digunakan lagi kapan saja dalam Namun, versi utama (mis. v1) akan tetap didukung hingga versi Utama versi dihentikan.

Rilis versi utama

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

Ad Manager REST API tidak memiliki ritme rilis reguler untuk Utama versi. Versi Utama baru hanya akan dirilis jika diperlukan.

Rilis di tempat

Perubahan yang kompatibel dengan versi lama termasuk fitur baru dan perbaikan bug dirilis diterapkan pada versi Major API saat ini. Klien harus menangani kolom yang tidak diketahui dalam respons API.

Kompatibilitas Mundur

Kompatibilitas mundur dipertahankan untuk perubahan dalam versi Utama. Kompatibilitas didefinisikan sebagai:

  1. Kompatibilitas sumber: Kode yang ditulis berdasarkan kompilasi rilis sebelumnya terhadap rilis yang lebih baru, dan berhasil berjalan dengan versi yang lebih baru dari library klien.

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

  3. Kompatibilitas semantik: Kode yang ditulis berdasarkan versi sebelumnya berlanjut untuk mendapatkan apa yang diharapkan pengembang paling masuk akal.

Tabel berikut mencantumkan jenis perubahan API dan apakah perubahan tersebut dipertimbangkan kompatibel dengan teknologi lama.

Layanan

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

Metode

Jenis Perubahan Kompatibel dengan versi lama
Tambahkan metode baru Ya
Menghapus metode Tidak
Mengubah jenis permintaan atau respons metode Tidak

Objek

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

Enumerasi

Jenis Perubahan Kompatibel dengan versi lama
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, kedua kolom dapat ditetapkan. Menyertakan kedua kolom dalam update permintaan 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 mengisi kedua kolom dengan nilai yang setara:

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

Permintaan update dapat menetapkan salah satu nilai. Menyertakan kedua {i>field<i} akan menghasilkan INVALID_ARGUMENT error:

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. Info terbaru dapat diabaikan.

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