Status

Tipe Status mendefinisikan model kesalahan logis yang cocok untuk berbagai lingkungan pemrograman, termasuk REST API dan RPC API. Ini digunakan oleh gRPC . Model kesalahan dirancang untuk menjadi:

  • Mudah digunakan dan dipahami oleh sebagian besar pengguna
  • Cukup fleksibel untuk memenuhi kebutuhan tak terduga

Ringkasan

Pesan Status berisi tiga bagian data: kode kesalahan, pesan kesalahan, dan detail kesalahan. Kode kesalahan harus berupa nilai enum dari google.rpc.Code , namun dapat menerima kode kesalahan tambahan jika diperlukan. Pesan kesalahan harus berupa pesan berbahasa Inggris yang ditujukan kepada pengembang yang membantu pengembang memahami dan mengatasi kesalahan tersebut. Jika pesan kesalahan yang dilihat pengguna yang dilokalkan diperlukan, letakkan pesan yang dilokalkan itu di detail kesalahan atau lokalkan pesan itu di klien. Detail kesalahan opsional mungkin berisi informasi sewenang-wenang tentang kesalahan tersebut. Ada serangkaian jenis detail kesalahan yang telah ditentukan sebelumnya dalam paket google.rpc yang dapat digunakan untuk kondisi kesalahan umum.

Pemetaan bahasa

Pesan Status adalah representasi logis dari model kesalahan, namun belum tentu merupakan format kabel sebenarnya. Ketika pesan Status diekspos di perpustakaan klien yang berbeda dan protokol kabel yang berbeda, pesan tersebut dapat dipetakan secara berbeda. Misalnya, kemungkinan besar akan dipetakan ke beberapa pengecualian di Java, namun lebih mungkin dipetakan ke beberapa kode kesalahan di C.

Penggunaan lainnya

Model kesalahan dan pesan Status dapat digunakan di berbagai lingkungan, baik dengan atau tanpa API, untuk memberikan pengalaman pengembang yang konsisten di berbagai lingkungan.

Contoh penggunaan model kesalahan ini meliputi:

  • Kesalahan sebagian. Jika suatu layanan perlu mengembalikan kesalahan parsial ke klien, layanan tersebut mungkin menyematkan Status dalam respons normal untuk menunjukkan kesalahan parsial.

  • Kesalahan alur kerja. Alur kerja tipikal memiliki beberapa langkah. Setiap langkah mungkin memiliki pesan Status untuk pelaporan kesalahan.

  • Operasi batch. Jika klien menggunakan permintaan batch dan respons batch, pesan Status harus digunakan langsung di dalam respons batch, satu untuk setiap sub-respons kesalahan.

  • Operasi asinkron. Jika panggilan API yang menyematkan operasi asinkron menghasilkan responsnya, status operasi tersebut harus direpresentasikan secara langsung menggunakan pesan Status .

  • Pencatatan. Jika beberapa kesalahan API disimpan dalam log, pesan Status dapat digunakan langsung setelah penghapusan apa pun yang diperlukan untuk alasan keamanan/privasi.

Representasi JSON
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
bidang
code

number

Kode status, yang seharusnya merupakan nilai enum dari google.rpc.Code .

message

string

Pesan kesalahan yang ditujukan kepada pengembang, yang seharusnya dalam bahasa Inggris. Pesan kesalahan apa pun yang dilihat pengguna harus dilokalkan dan dikirim di bidang google.rpc.Status.details , atau dilokalkan oleh klien.

details[]

object

Daftar pesan yang berisi rincian kesalahan. Ada serangkaian jenis pesan umum yang dapat digunakan oleh API.

Objek yang berisi bidang dengan tipe arbitrer. Bidang tambahan "@type" berisi URI yang mengidentifikasi jenisnya. Contoh: { "id": 1234, "@type": "types.example.com/standard/id" } .