Status

Status türü, REST API'ler ve RPC API'leri dahil olmak üzere farklı programlama ortamları için uygun bir mantıksal hata modelini tanımlar. gRPC tarafından kullanılır. Hata modeli şu özelliklere sahip olacak şekilde tasarlanmıştır:

  • Çoğu kullanıcı için kullanımı kolaydır ve anlaşılır
  • Beklenmedik ihtiyaçları karşılayacak kadar esnektir

Genel Bakış

Status mesajı üç veri parçası içerir: hata kodu, hata mesajı ve hata ayrıntıları. Hata kodu google.rpc.Code değerindeki bir numaralandırma değeri olmalıdır ancak gerekirse ek hata kodları kabul edebilir. Hata mesajı, geliştiricilerin hatayı anlayıp çözmesine yardımcı olan, geliştiricilere yönelik İngilizce bir mesaj olmalıdır. Kullanıcılara yönelik yerelleştirilmiş bir hata mesajı gerekiyorsa yerelleştirilmiş mesajı hata ayrıntılarına ekleyin veya istemcide yerelleştirin. İsteğe bağlı hata ayrıntılarında hatayla ilgili rastgele bilgiler yer alabilir. google.rpc paketinde, yaygın hata koşulları için kullanılabilecek önceden tanımlanmış bir dizi hata ayrıntısı türü vardır.

Dil eşleme

Status mesajı, hata modelinin mantıksal temsilidir ancak gerçek kablo biçimi olmayabilir. Status mesajı, farklı istemci kitaplıklarında ve farklı kablo protokollerinde sunulduğunda farklı şekilde eşlenebilir. Örneğin, büyük olasılıkla Java'daki bazı istisnalarla, ancak daha büyük olasılıkla C'deki bazı hata kodlarıyla eşlenir.

Diğer kullanım alanları

Hata modeli ve Status mesajı, farklı ortamlarda tutarlı bir geliştirici deneyimi sunmak için API'lerle veya API'ler olmadan çeşitli ortamlarda kullanılabilir.

Bu hata modelinin kullanım örnekleri arasında şunlar yer alır:

  • Kısmi hatalar. Bir hizmetin istemciye kısmi hatalar döndürmesi gerekiyorsa kısmi hataları belirtmek için normal yanıta Status öğesini yerleştirebilir.

  • İş akışı hataları. Tipik bir iş akışında birden fazla adım bulunur. Her adımda hata bildirimi için bir Status mesajı bulunabilir.

  • Toplu işlemler. Bir istemci toplu istek ve toplu yanıt kullanıyorsa Status mesajı, her hata alt yanıtı için bir tane olmak üzere doğrudan toplu yanıtın içinde kullanılmalıdır.

  • Eşzamansız işlemler. Bir API çağrısı, eşzamansız işlem sonuçlarını yerleştirirse bu işlemlerin durumu doğrudan Status mesajıyla gösterilmelidir.

  • Günlük kaydı. Günlüklerde bazı API hataları depolanıyorsa güvenlik/gizlilik nedeniyle gerekli çıkarma işleminden hemen sonra Status mesajı kullanılabilir.

JSON gösterimi 
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Alanlar
code

number

google.rpc.Code olması gereken durum kodu.

message

string

Geliştiricilere yönelik, İngilizce olması gereken bir hata mesajı. Kullanıcılara yönelik tüm hata mesajları yerelleştirilip google.rpc.Status.details alanında gönderilmeli veya istemci tarafından yerelleştirilmelidir.

details[]

object

Hata ayrıntılarını içeren mesajların listesi. API'lerin kullandığı bir dizi mesaj türü vardır.

Rastgele türden alanlar içeren nesne. Ek bir "@type" alanı, türü tanımlayan bir URI içerir. Örnek: { "id": 1234, "@type": "types.example.com/standard/id" }.