Status

Status türü, REST API'leri ve RPC API'leri dahil olmak üzere farklı programlama ortamlarına uygun bir mantıksal hata modeli tanımlar. GRPC tarafından kullanılır. Hata modeli şu şekilde tasarlanmıştır:

  • Çoğu kullanıcı için kullanımı ve anlaşılması basit
  • Beklenmedik ihtiyaçları karşılayacak kadar esnek

Genel Bakış

Status mesajı üç parça veri içerir: hata kodu, hata mesajı ve hata ayrıntıları. Hata kodu google.rpc.Code bir numaralandırma değeri olmalıdır, ancak gerekirse ek hata kodları da kabul edilebilir. Hata mesajı, geliştiricilerin hatayı anlamasına ve çözmesine yardımcı olan, geliştiriciye yönelik İngilizce bir mesaj olmalıdır. Kullanıcının karşılaştığı 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ı, hatayla ilgili isteğe bağlı bilgiler içerebilir. 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 iletim formatı olması şart değildir. Status mesajı farklı istemci kitaplıklarında ve farklı kablo protokollerinde gösterildiğinde farklı şekilde eşlenebilir. Örneğin, muhtemelen Java'daki bazı istisnalarla eşlenecektir, ancak büyük olasılıkla C'deki bazı hata kodlarıyla eşlenecektir.

Diğer kullanımlar

Hata modeli ve Status mesajı, farklı ortamlarda tutarlı bir geliştirici deneyimi sağlamak için API'li veya API'siz çeşitli ortamlarda kullanılabilir.

Bu hata modelinin örnek kullanımları şunları içerir:

  • Kısmi hatalar. Bir hizmetin istemciye kısmi hatalar döndürmesi gerekiyorsa, kısmi hataları belirtmek için Status normal yanıta ekleyebilir.

  • İş akışı hataları. Tipik bir iş akışının birden çok adımı vardır. Her adımda hata raporlama için bir Status mesajı bulunabilir.

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

  • Asenkron işlemler. Bir API çağrısı, yanıtında eşzamansız işlem sonuçları içeriyorsa, bu işlemlerin durumu doğrudan Status mesajı kullanılarak gösterilmelidir.

  • Kerestecilik. Bazı API hataları günlüklerde saklanıyorsa, güvenlik/gizlilik nedenleriyle gereken herhangi bir ayırma işleminin ardından Status mesajı doğrudan kullanılabilir.

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

number

google.rpc.Code öğesinin numaralandırma değeri olması gereken durum kodu.

message

string

İngilizce olması gereken, geliştiricinin karşılaştığı bir hata mesajı. Kullanıcının karşılaştığı herhangi bir hata mesajı yerelleştirilip google.rpc.Status.details alanına gönderilmeli veya istemci tarafından yerelleştirilmelidir.

details[]

object

Hata ayrıntılarını taşıyan mesajların listesi. API'lerin kullanabileceği ortak bir mesaj türleri kümesi vardır.

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