Error Google Distributed Cloud dengan air gap

Bab ini memberikan ringkasan model error untuk API Google Distributed Cloud dengan air gap (GDC). Artikel ini juga memberikan panduan umum kepada developer tentang cara membuat dan menangani error dengan benar.

GDC API menggunakan model error sederhana yang agnostik terhadap protokol, sehingga kami dapat menawarkan pengalaman yang konsisten di berbagai API, berbagai protokol API (seperti gRPC atau HTTP), dan berbagai konteks error (seperti error asinkron, batch, atau alur kerja).

Model error

Model error untuk GDC API secara logis ditentukan oleh google.rpc.Status, yang instance-nya ditampilkan ke klien saat terjadi error API. Cuplikan kode berikut menunjukkan desain keseluruhan model error:

package google.rpc;

// The `Status` type defines a logical error model that is suitable for
// different programming environments, including REST APIs and RPC APIs.
message Status {
  // A simple error code that can be easily handled by the client. The
  // actual error code is defined by `google.rpc.Code`.
  int32 code = 1;

  // A developer-facing human-readable error message in English. It should
  // both explain the error and offer an actionable resolution to it.
  string message = 2;

  // Additional error information that the client code can use to handle
  // the error, such as retry info or a help link.
  repeated google.protobuf.Any details = 3;
}

Karena sebagian besar Google API menggunakan desain API berorientasi resource, penanganan error mengikuti prinsip desain yang sama dengan menggunakan serangkaian kecil error standar dengan sejumlah besar resource. Misalnya, alih-alih menentukan berbagai jenis error "tidak ditemukan", server menggunakan satu kode error google.rpc.Code.NOT_FOUND standar dan memberi tahu klien resource spesifik mana yang tidak ditemukan. Ruang error yang lebih kecil mengurangi kompleksitas dokumentasi, memberikan pemetaan idiomatis yang lebih baik di library klien, dan mengurangi kompleksitas logika klien tanpa membatasi penyertaan informasi yang dapat ditindaklanjuti.

Catatan: Saat menggunakan gRPC, error disertakan dalam header, dan total header dalam respons dibatasi hingga 8 KB (8.192 byte). Pastikan ukuran error tidak melebihi 1-2 KB.

Kode error

GDC API harus menggunakan kode error kanonis yang ditentukan oleh google.rpc.Code. API individual harus menghindari penentuan kode error tambahan, karena developer sangat tidak mungkin menulis logika untuk menangani sejumlah besar kode error. Sebagai referensi, penanganan rata-rata tiga kode error per panggilan API akan berarti sebagian besar logika aplikasi hanya untuk penanganan error, yang tidak akan memberikan pengalaman developer yang baik.

Pesan error

Pesan error harus membantu pengguna memahami dan mengatasi error API dengan mudah dan cepat. Secara umum, pertimbangkan panduan berikut saat menulis pesan error:

• Jangan menganggap pengguna adalah pakar API Anda. Pengguna dapat berupa developer klien, staf operasi, staf IT, atau pengguna akhir aplikasi.
• Jangan menganggap pengguna mengetahui apa pun tentang penerapan layanan Anda atau memahami konteks error (seperti analisis log).
• Jika memungkinkan, pesan error harus dibuat sedemikian rupa sehingga pengguna teknis (tetapi tidak harus developer API Anda) dapat merespons error dan memperbaikinya.
• Buat pesan error yang singkat. Jika perlu, berikan link tempat pembaca yang bingung dapat mengajukan pertanyaan, memberikan masukan, atau mendapatkan informasi lebih lanjut yang tidak sesuai dengan pesan error. Jika tidak, gunakan kolom detail untuk meluaskan.

Peringatan: Pesan error bukan bagian dari permukaan API. Dapat berubah tanpa pemberitahuan. Kode aplikasi tidak boleh memiliki dependensi kuat pada pesan error.

Error details

GDC API menentukan serangkaian payload error standar untuk detail error, yang dapat Anda temukan di google/rpc/error_details.proto. Error ini mencakup kebutuhan paling umum untuk error API, seperti kegagalan kuota dan parameter tidak valid. Seperti kode error, developer harus menggunakan payload standar ini jika memungkinkan.

Jenis detail error tambahan hanya boleh diperkenalkan jika dapat membantu kode aplikasi menangani error. Jika informasi error hanya dapat ditangani oleh manusia, andalkan konten pesan error dan biarkan developer menanganinya secara manual, daripada memperkenalkan jenis detail error tambahan.

Berikut beberapa contoh payload error_details:

• ErrorInfo: Menyediakan informasi error terstruktur yang stabil dan dapat diperluas.
• RetryInfo: Menjelaskan kapan klien dapat mencoba lagi permintaan yang gagal, dapat ditampilkan pada Code.UNAVAILABLE atau Code.ABORTED
• QuotaFailure: Menjelaskan kegagalan pemeriksaan kuota, dapat ditampilkan di Code.RESOURCE_EXHAUSTED
• BadRequest: Menjelaskan pelanggaran dalam permintaan klien, dapat ditampilkan di Code.INVALID_ARGUMENT

Info error

ErrorInfo adalah jenis payload error khusus. API ini memberikan informasi error yang stabil dan dapat diperluas yang dapat diandalkan oleh manusia dan aplikasi. Setiap ErrorInfo memiliki tiga bagian informasi: domain error, alasan error, dan serangkaian metadata error. Untuk mengetahui informasi selengkapnya, lihat definisi ErrorInfo.

Untuk GDC API, domain error utama adalah googleapis.com, dan alasan error yang sesuai ditentukan oleh enum google.api.ErrorReason. Untuk mengetahui informasi selengkapnya, lihat definisi google.api.ErrorReason.

Lokalitas error

Kolom message di google.rpc.Status ditampilkan kepada developer dan harus dalam bahasa Inggris.

Jika pesan error yang ditampilkan kepada pengguna diperlukan, gunakan google.rpc.LocalizedMessage sebagai kolom detail Anda. Meskipun kolom pesan di google.rpc.LocalizedMessage dapat dilokalkan, pastikan kolom pesan di google.rpc.Status berbahasa Inggris.

Secara default, layanan API harus menggunakan lokalitas pengguna yang diautentikasi atau header HTTP Accept-Language atau parameter language_code dalam permintaan untuk menentukan bahasa untuk pelokalan.

Pemetaan error

GDC API dapat diakses di lingkungan pemrograman yang berbeda. Setiap lingkungan biasanya memiliki cara penanganan error sendiri. Bagian berikut menjelaskan cara memetakan model error di lingkungan yang umum digunakan.

Pemetaan HTTP

Meskipun pesan proto3 memiliki encoding JSON native, platform GDC API menggunakan skema error yang berbeda untuk GDC JSON HTTP API karena alasan kompatibilitas mundur.

Skema:

// This message defines the error schema for GDC JSON HTTP APIs.
message Error {
  // Deprecated. This message is only used by error format v1.
  message ErrorProto {}
  // This message has the same semantics as `google.rpc.Status`. It uses HTTP
  // status code instead of gRPC status code. It has extra fields `status` and
  // `errors` for backward compatibility with [GDC API Client
  // Libraries](https://developers.google.com/api-client-library).
  message Status {
    // The HTTP status code that corresponds to `google.rpc.Status.code`.
    int32 code = 1;
    // This corresponds to `google.rpc.Status.message`.
    string message = 2;
    // Deprecated. This field is only used by error format v1.
    repeated ErrorProto errors = 3;
    // This is the enum version for `google.rpc.Status.code`.
    google.rpc.Code status = 4;
    // This corresponds to `google.rpc.Status.details`.
    repeated google.protobuf.Any details = 5;
  }
  // The actual error payload. The nested message structure is for backward
  // compatibility with [GDC API Client
  // Libraries](https://developers.google.com/api-client-library). It also
  // makes the error more readable to developers.
  Status error = 1;
}

Contoh:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "translate.googleapis.com"
        }
      }
    ]
  }
}

Pemetaan gRPC

Protokol RPC yang berbeda memetakan model error secara berbeda. Untuk gRPC, model error didukung secara native oleh kode yang dihasilkan dan library runtime dalam setiap bahasa yang didukung. Anda dapat mempelajari lebih lanjut di dokumentasi API gRPC. Misalnya, lihat io.grpc.Status gRPC Java.

Pemetaan library klien

Library klien GDC dapat memilih untuk menampilkan error secara berbeda per bahasa agar konsisten dengan idiom yang sudah ditetapkan. Misalnya, library google-cloud-go akan menampilkan error yang mengimplementasikan antarmuka yang sama dengan google.rpc.Status, sementara google-cloud-java akan memunculkan Pengecualian.

Menangani error

Tabel berikut berisi semua kode error gRPC yang ditentukan dalam google.rpc.Code dan deskripsi singkat tentang penyebabnya. Untuk menangani error, Anda dapat memeriksa deskripsi kode status yang ditampilkan dan mengubah panggilan Anda dengan tepat.

HTTP	gRPC	Deskripsi
200	OK	Tidak ada error.
400	INVALID_ARGUMENT	Klien menentukan argumen yang tidak valid. Periksa pesan error dan detail error untuk mengetahui informasi selengkapnya.
400	FAILED_PRECONDITION	Permintaan tidak dapat dijalankan dalam status sistem saat ini, seperti menghapus direktori yang tidak kosong.
400	OUT_OF_RANGE	Klien menentukan rentang yang tidak valid.
401	UNAUTHENTICATED	Permintaan tidak diautentikasi karena token OAuth tidak ada, tidak valid, atau sudah tidak berlaku.
403	PERMISSION_DENIED	Klien tidak memiliki izin yang memadai. Hal ini dapat terjadi karena token OAuth tidak memiliki cakupan yang tepat, klien tidak memiliki izin, atau API belum diaktifkan.
404	NOT_FOUND	Resource yang ditentukan tidak ditemukan.
409	ABORTED	Konflik serentak, seperti konflik baca-ubah-tulis.
409	ALREADY_EXISTS	Resource yang klien coba buat sudah ada.
429	RESOURCE_EXHAUSTED	Kuota resource telah habis atau mencapai pembatasan kapasitas. Klien harus mencari detail error google.rpc.QuotaFailure untuk mengetahui informasi selengkapnya.
499	CANCELLED	Permintaan dibatalkan oleh klien.
500	DATA_LOSS	Kehilangan data atau kerusakan data yang tidak dapat dipulihkan. Klien harus melaporkan error kepada pengguna.
500	UNKNOWN	Terjadi error yang tidak diketahui pada server. Biasanya merupakan bug server.
500	INTERNAL	Error server internal. Biasanya merupakan bug server.
501	NOT_IMPLEMENTED	Metode API tidak diimplementasikan oleh server.
502	T/A	Terjadi error jaringan sebelum menjangkau server. Biasanya karena gangguan atau kesalahan konfigurasi jaringan.
503	UNAVAILABLE	Layanan tidak tersedia. Biasanya server tidak berfungsi.
504	DEADLINE_EXCEEDED	Batas waktu permintaan terlampaui. Hal ini hanya akan terjadi jika pemanggil menetapkan batas waktu yang lebih singkat daripada batas waktu default metode (yaitu, batas waktu yang diminta tidak cukup bagi server untuk memproses permintaan) dan permintaan tidak selesai dalam batas waktu.

Peringatan: GDC API dapat secara bersamaan memeriksa beberapa prasyarat untuk permintaan API. Menampilkan satu kode error tidak berarti prakondisi lainnya terpenuhi. Kode aplikasi tidak boleh bergantung pada urutan pemeriksaan prasyarat.

Mencoba lagi error

Klien dapat mencoba lagi error 503 UNAVAILABLE dengan backoff eksponensial. Penundaan minimum harus 1 detik, kecuali jika didokumentasikan sebaliknya. Pengulangan coba ulang default harus dilakukan sekali, kecuali jika didokumentasikan sebaliknya.

Untuk error 429 RESOURCE_EXHAUSTED, klien dapat mencoba lagi pada tingkat yang lebih tinggi dengan penundaan minimal 30 detik. Upaya percobaan ulang tersebut hanya berguna untuk tugas latar belakang yang berjalan lama.

Untuk semua error lainnya, percobaan ulang mungkin tidak berlaku. Pertama, pastikan permintaan Anda bersifat idempoten, dan lihat google.rpc.RetryInfo untuk mendapatkan panduan.

Menyebarkan error

Jika layanan API Anda bergantung pada layanan lain, Anda tidak boleh menyebarkan kesalahan dari layanan tersebut ke klien Anda secara membabi buta. Saat menerjemahkan error, sebaiknya lakukan hal berikut:

• Sembunyikan detail penerapan dan informasi rahasia.
• Sesuaikan pihak yang bertanggung jawab atas kesalahan tersebut. Misalnya, server yang menerima error INVALID_ARGUMENT dari layanan lain harus menyebarkan INTERNAL ke pemanggilnya sendiri.

Mengulangi error

Jika Anda tidak dapat menyelesaikan error melalui analisis log dan pemantauan, Anda harus mencoba mereproduksi error dengan pengujian yang sederhana dan dapat diulang. Anda dapat menggunakan pengujian untuk mengumpulkan informasi selengkapnya untuk pemecahan masalah, yang dapat Anda berikan saat menghubungi dukungan teknis.

Sebaiknya gunakan oauth2l dan curl -v serta Parameter Sistem untuk mereproduksi error dengan GDC API. Bersama-sama, keduanya dapat mereproduksi hampir semua permintaan GDC API, dan memberikan informasi debug yang lengkap kepada Anda. Untuk mengetahui informasi selengkapnya, lihat halaman dokumentasi masing-masing API yang Anda panggil.

Membuat kesalahan

Jika Anda adalah developer server, Anda harus menghasilkan error dengan informasi yang cukup untuk membantu developer klien memahami dan menyelesaikan masalah. Pada saat yang sama, Anda harus memahami keamanan dan privasi data pengguna, serta menghindari pengungkapan informasi sensitif dalam pesan error dan detail error, karena error sering dicatat dan mungkin dapat diakses oleh orang lain. Misalnya, pesan error seperti "Alamat IP klien tidak ada dalam daftar yang diizinkan 128.0.0.0/8" mengekspos informasi tentang kebijakan sisi server, yang mungkin tidak dapat diakses oleh pengguna yang memiliki akses ke log.

Untuk membuat error yang tepat, Anda harus memahami google.rpc.Code terlebih dahulu untuk memilih kode error yang paling sesuai untuk setiap kondisi error. Aplikasi server dapat memeriksa beberapa kondisi error secara paralel, dan menampilkan yang pertama.

Tabel berikut mencantumkan setiap kode error dan contoh pesan error yang baik.

HTTP	gRPC	Contoh Pesan Error
400	INVALID_ARGUMENT	Kolom permintaan x.y.z adalah xxx, yang diharapkan adalah salah satu dari [yyy, zzz].
400	FAILED_PRECONDITION	Resource xxx adalah direktori yang tidak kosong, sehingga tidak dapat dihapus.
400	OUT_OF_RANGE	Parameter 'age' di luar rentang [0, 125].
401	UNAUTHENTICATED	Kredensial autentikasi tidak valid.
403	PERMISSION_DENIED	Izin 'xxx' ditolak pada resource 'yyy'.
404	NOT_FOUND	Resource 'xxx' tidak ditemukan.
409	ABORTED	Tidak dapat memperoleh kunci pada resource 'xxx.
409	ALREADY_EXISTS	Resource 'xxx' sudah ada.
429	RESOURCE_EXHAUSTED	Batas kuota 'xxx' terlampaui.
499	CANCELLED	Permintaan dibatalkan oleh klien.
500	DATA_LOSS	Lihat catatan.
500	UNKNOWN	Lihat catatan.
500	INTERNAL	Lihat catatan.
501	NOT_IMPLEMENTED	Metode 'xxx' tidak diterapkan.
503	UNAVAILABLE	Lihat catatan.
504	DEADLINE_EXCEEDED	Lihat catatan.

Catatan: Karena klien tidak dapat memperbaiki error server, tidak ada gunanya membuat detail error tambahan. Untuk menghindari kebocoran informasi sensitif dalam kondisi error, sebaiknya jangan membuat pesan error apa pun dan hanya membuat detail error google.rpc.DebugInfo. DebugInfo dirancang khusus hanya untuk logging sisi server, dan tidak boleh dikirim ke klien.

Payload error

Paket google.rpc menentukan serangkaian payload error standar, yang lebih disukai daripada payload error kustom. Tabel berikut mencantumkan setiap kode error dan payload error standarnya yang cocok, jika ada. Sebaiknya aplikasi lanjutan mencari payload error ini di google.rpc.Status saat menangani error.

HTTP	gRPC	Detail Error yang Direkomendasikan
400	INVALID_ARGUMENT	google.rpc.BadRequest
400	FAILED_PRECONDITION	google.rpc.PreconditionFailure
400	OUT_OF_RANGE	google.rpc.BadRequest
401	UNAUTHENTICATED	google.rpc.ErrorInfo
403	PERMISSION_DENIED	google.rpc.ErrorInfo
404	NOT_FOUND	google.rpc.ResourceInfo
409	ABORTED	google.rpc.ErrorInfo
409	ALREADY_EXISTS	google.rpc.ResourceInfo
429	RESOURCE_EXHAUSTED	google.rpc.QuotaFailure
499	CANCELLED
500	DATA_LOSS	google.rpc.DebugInfo
500	UNKNOWN	google.rpc.DebugInfo
500	INTERNAL	google.rpc.DebugInfo
501	NOT_IMPLEMENTED
503	UNAVAILABLE	google.rpc.DebugInfo
504	DEADLINE_EXCEEDED	google.rpc.DebugInfo