Package google.rpc

Dizin

BadRequest

İstemci isteğindeki ihlalleri açıklar. Bu hata türü, isteğin söz dizimiyle ilgili yönlerine odaklanır.

Alanlar
field_violations[]

FieldViolation

İstemci isteğindeki tüm ihlalleri açıklar.

FieldViolation

Tek bir hatalı istek alanını açıklamak için kullanılan mesaj türü.

Alanlar
field

string

İstek gövdesindeki bir alana giden yol. Değer, bir protokol arabelleği alanını tanımlayan, nokta ile ayrılmış tanımlayıcılar dizisi olur.

Aşağıdakileri göz önünde bulundurun:

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

Bu örnekte, proto field aşağıdaki değerlerden birini alabilir:

  • full_name değerindeki bir ihlal için full_name
  • İlk email_addresses iletisinin email alanındaki bir ihlal için email_addresses[1].email
  • Üçüncü email_addresses mesajdaki ikinci type değerinde email_addresses[3].type[2] ihlali için.

JSON'da aynı değerler şu şekilde gösterilir:

  • fullName değerindeki bir ihlal için fullName
  • İlk emailAddresses iletisinin email alanındaki bir ihlal için emailAddresses[1].email
  • Üçüncü emailAddresses mesajdaki ikinci type değerinde emailAddresses[3].type[2] ihlali için.
description

string

İstek öğesinin neden kötü olduğuna dair açıklama.
reason

string

Alan düzeyindeki hatanın nedeni. Bu, alan düzeyindeki hatanın asıl nedenini tanımlayan sabit bir değerdir. google.rpc.ErrorInfo.domain kapsamındaki FieldViolation türünü benzersiz şekilde tanımlamalıdır. Bu değer en fazla 63 karakter olmalı ve UPPER_SNAKE_CASE'i temsil eden [A-Z][A-Z0-9_]+[A-Z0-9] normal ifadesiyle eşleşmelidir.
localized_message

LocalizedMessage

Alan düzeyindeki hatalar için API tüketicisine döndürülmesi güvenli olan yerelleştirilmiş bir hata mesajı sağlar.

Kod

gRPC API'leri için standart hata kodları.

Bazen birden fazla hata kodu geçerli olabilir. Hizmetler, geçerli olan en spesifik hata kodunu döndürmelidir. Örneğin, her iki kod da geçerliyse FAILED_PRECONDITION yerine OUT_OF_RANGE kodunu tercih edin. Benzer şekilde, FAILED_PRECONDITION yerine NOT_FOUND veya ALREADY_EXISTS tercih edin.

Sıralamalar
OK

Hata değildir; başarıyla döndürülür.

HTTP Eşleme: 200 OK
CANCELLED

İşlem, genellikle arayan tarafından iptal edildi.

HTTP Eşleme: 499 İstemci İsteği Kapattı
UNKNOWN

Bilinmeyen hata. Örneğin, başka bir adres alanından alınan bir Status değeri, bu adres alanında bilinmeyen bir hata alanına ait olduğunda bu hata döndürülebilir. Ayrıca, yeterli hata bilgisi döndürmeyen API'lerin oluşturduğu hatalar da bu hataya dönüştürülebilir.

HTTP Eşleme: 500 Dahili Sunucu Hatası
INVALID_ARGUMENT

İstemci, geçersiz bir bağımsız değişken belirtti. Bunun FAILED_PRECONDITION'dan farklı olduğunu unutmayın. INVALID_ARGUMENT, sistemin durumundan bağımsız olarak sorunlu olan bağımsız değişkenleri (ör. hatalı biçimlendirilmiş bir dosya adı) gösterir.

HTTP Eşleme: 400 Hatalı İstek
DEADLINE_EXCEEDED

İşlem tamamlanmadan son tarih geçti. Sistemin durumunu değiştiren işlemler için, işlem başarıyla tamamlanmış olsa bile bu hata döndürülebilir. Örneğin, bir sunucudan gelen başarılı yanıt, son kullanma tarihinin geçmesine yetecek kadar uzun süre gecikmiş olabilir.

HTTP Eşleme: 504 Ağ Geçidi Zaman Aşımı
NOT_FOUND

İstenen bazı öğeler (ör. dosya veya dizin) bulunamadı.

Sunucu geliştiricilerine not: Bir istek, kademeli özellik kullanıma sunma veya belgelenmemiş izin verilenler listesi gibi tüm kullanıcı sınıfı için reddedilirse NOT_FOUND kullanılabilir. Kullanıcı tabanlı erişim kontrolü gibi bir kullanıcı sınıfındaki bazı kullanıcıların isteği reddedilirse PERMISSION_DENIED kullanılmalıdır.

HTTP Eşlemesi: 404 Bulunamadı
ALREADY_EXISTS

Bir istemcinin oluşturmaya çalıştığı varlık (ör. dosya veya dizin) zaten mevcut.

HTTP eşleme: 409 Çakışma
PERMISSION_DENIED

Arayan kullanıcının belirtilen işlemi gerçekleştirme izni yok. PERMISSION_DENIED, bazı kaynakların tükenmesinden kaynaklanan retler için kullanılmamalıdır (bu tür hatalar için bunun yerine RESOURCE_EXHAUSTED kullanılmalıdır). Arayan tanımlanamıyorsa PERMISSION_DENIED kullanılmamalıdır (bu tür hatalar için bunun yerine UNAUTHENTICATED kullanılmalıdır). Bu hata kodu, isteğin geçerli olduğunu veya istenen öğenin mevcut olduğunu ya da diğer ön koşulları karşıladığını göstermez.

HTTP Eşlemesi: 403 Yasaklandı
UNAUTHENTICATED

İstekte işlemle ilgili geçerli kimlik doğrulama bilgileri bulunmuyor.

HTTP Eşlemesi: 401 Yetkisiz
RESOURCE_EXHAUSTED

Kullanıcı başına kota veya dosya sisteminin tamamında yer kalmaması gibi bir kaynak tükenmiş olabilir.

HTTP Eşleme: 429 Çok Fazla İstek Var
FAILED_PRECONDITION

Sistem, işlemin yürütülmesi için gerekli durumda olmadığından işlem reddedildi. Örneğin, silinecek dizinin boş olmaması, rmdir işleminin dizin olmayan bir öğeye uygulanması vb.

Hizmet uygulayıcıları, FAILED_PRECONDITION, ABORTED ve UNAVAILABLE arasında karar vermek için aşağıdaki yönergeleri kullanabilir: (a) İstemci yalnızca başarısız olan çağrıyı yeniden deneyebiliyorsa UNAVAILABLE kullanın. (b) İstemcinin daha yüksek bir düzeyde yeniden denemesi gerekiyorsa ABORTED kullanın. Örneğin, istemci tarafından belirtilen bir test ve ayarlama işlemi başarısız olduğunda istemcinin bir okuma-değiştirme-yazma dizisini yeniden başlatması gerektiğini belirtir. (c) Sistem durumu açıkça düzeltilene kadar istemcinin yeniden denememesi gerekiyorsa FAILED_PRECONDITION kullanın. Örneğin, bir "rmdir" işlemi dizin boş olmadığı için başarısız olursa istemci, dosyalar dizinden silinmediği sürece yeniden denememelidir. Bu nedenle FAILED_PRECONDITION döndürülmelidir.

HTTP Eşleme: 400 Hatalı İstek
ABORTED

İşlem, genellikle sıralayıcı kontrolü hatası veya işlem iptali gibi eşzamanlılık sorunu nedeniyle iptal edildi.

FAILED_PRECONDITION, ABORTED ve UNAVAILABLE arasında karar vermek için yukarıdaki kuralları inceleyin.

HTTP eşleme: 409 Çakışma
OUT_OF_RANGE

İşlem, geçerli aralığın dışında denenmiş. Örneğin, dosya sonunun ötesinde arama yapma veya okuma

INVALID_ARGUMENT hatasının aksine bu hata, sistem durumu değiştiğinde düzeltilebilecek bir soruna işaret eder. Örneğin, [0,2^32-1] aralığında olmayan bir ofsetten okuması istendiğinde 32 bitlik bir dosya sistemi INVALID_ARGUMENT oluşturur ancak geçerli dosya boyutunu aşan bir ofsetten okuması istendiğinde OUT_OF_RANGE oluşturur.

FAILED_PRECONDITION ile OUT_OF_RANGE arasında önemli bir örtüşme var. Bir alan üzerinde yineleme yapan arayanların, işleri bittiğinde bunu tespit etmek için OUT_OF_RANGE hatasını kolayca arayabilmesi amacıyla geçerli olduğunda OUT_OF_RANGE (daha spesifik hata) kullanılmasını öneririz.

HTTP Eşleme: 400 Hatalı İstek
UNIMPLEMENTED

İşlem uygulanmamıştır veya bu hizmette desteklenmiyor/etkinleştirilmemiştir.

HTTP Eşleme: 501 Uygulanmadı
INTERNAL

Dahili hatalar. Bu, temel sistemin beklediği bazı değişmezlerin bozulduğu anlamına gelir. Bu hata kodu ciddi hatalar için ayrılmıştır.

HTTP Eşleme: 500 Dahili Sunucu Hatası
UNAVAILABLE

Hizmet şu anda kullanılamıyor. Bu durum büyük olasılıkla geçicidir ve geri çekilme ile yeniden denenerek düzeltilebilir. İdempotent olmayan işlemleri yeniden denemenin her zaman güvenli olmadığını unutmayın.

FAILED_PRECONDITION, ABORTED ve UNAVAILABLE arasında karar vermek için yukarıdaki kuralları inceleyin.

HTTP Eşleme: 503 Hizmet Kullanılamıyor
DATA_LOSS

Kurtarılamaz veri kaybı veya bozulması.

HTTP Eşleme: 500 Dahili Sunucu Hatası

ErrorInfo

Yapılandırılmış ayrıntılarla hatanın nedenini açıklar.

Etkinleştirilmemiş "pubsub.googleapis.com" API'siyle iletişim kurulurken oluşan hata örneği:

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

Bu yanıt, pubsub.googleapis.com API'sinin etkin olmadığını gösterir.

Stokta olmayan bir bölgede Spanner örneği oluşturulmaya çalışılırken döndürülen hata örneği:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
Alanlar
reason

string

Hatanın nedeni. Bu, hatanın asıl nedenini tanımlayan sabit bir değerdir. Hata nedenleri, belirli bir hata alanında benzersizdir. Bu değer en fazla 63 karakter olmalı ve UPPER_SNAKE_CASE'i temsil eden [A-Z][A-Z0-9_]+[A-Z0-9] normal ifadesiyle eşleşmelidir.
domain

string

"Nedeni"n ait olduğu mantıksal gruplandırma. Hata alanı genellikle hatayı oluşturan aracın veya ürünün kayıtlı hizmet adıdır. Örnek: "pubsub.googleapis.com". Hata, ortak bir altyapı tarafından oluşturuluyorsa hata alanı, altyapıyı tanımlayan küresel olarak benzersiz bir değer olmalıdır. Google API altyapısı için hata alanı "googleapis.com"dur.
metadata

map<string, string>

Bu hatayla ilgili ek yapılandırılmış ayrıntılar.

Anahtarlar, [a-z][a-zA-Z0-9-_]+ normal ifadesiyle eşleşmelidir ancak ideal olarak lowerCamelCase olmalıdır. Ayrıca, uzunlukları 64 karakterle sınırlı olmalıdır. Aşılan bir sınırın mevcut değeri tanımlanırken birimler değerde değil, anahtarda yer almalıdır. Örneğin, istemci tek bir (toplu) istekte oluşturulabilecek örnek sayısını aşarsa {"instanceLimit": "100/request"} yerine {"instanceLimitPerRequest": "100"} döndürülmelidir.

Yardım

Belgelere veya bant dışı işlem yapmaya yönelik bağlantılar sağlar.

Örneğin, bir kota kontrolü, çağıran projenin erişilen hizmeti etkinleştirmediğini belirten bir hatayla başarısız olursa bu, bitin değiştirileceği geliştirici konsolundaki doğru yere doğrudan yönlendiren bir URL içerebilir.

Alanlar

LocalizedMessage

TBG hatasına eklenebilecek, kullanıcıya döndürülmesi güvenli olan yerelleştirilmiş bir hata mesajı sağlar.

Alanlar
locale

string

https://www.rfc-editor.org/rfc/bcp/bcp47.txt adresinde tanımlanan spesifikasyona göre kullanılan yerel ayar. Örnekler: "en-US", "fr-CH", "es-MX"
message

string

Yukarıdaki yerel ayarda yerelleştirilmiş hata mesajı.

PreconditionFailure

Hangi ön koşulların başarısız olduğunu açıklar.

Örneğin, bir RPC, Hizmet Şartları'nın onaylanmasını gerektirdiği için başarısız olursa PreconditionFailure mesajında hizmet şartları ihlali listelenebilir.

Alanlar
violations[]

Violation

Tüm ön koşul ihlallerini açıklar.

İhlal

Tek bir ön koşul hatasını açıklamak için kullanılan mesaj türü.

Alanlar
type

string

PreconditionFailure türü. Desteklenen ön koşul ihlali konularını tanımlamak için hizmete özgü bir enum türü kullanmanızı öneririz. Örneğin, "HŞ" (Hizmet Şartları ihlali).
subject

string

Türüne göre başarısız olan konu. Örneğin, "google.com/cloud" URL'si, "Hizmet Şartları" türüne göre hangi hizmet şartlarına referans verildiğini gösterir.
description

string

Ön koşulun nasıl karşılanmadığına dair açıklama. Geliştiriciler, bu açıklamayı kullanarak hatayı nasıl düzelteceklerini anlayabilirler.

Örneğin: "Hizmet şartları kabul edilmedi".

QuotaFailure

Kota kontrolünün nasıl başarısız olduğunu açıklar.

Örneğin, arayan proje için günlük sınır aşılırsa bir hizmet, proje kimliğini ve aşılan kota sınırının açıklamasını içeren bir QuotaFailure ayrıntısıyla yanıt verebilir. Çağrı yapan proje, hizmeti geliştirici konsolunda etkinleştirmediyse hizmet, proje kimliğiyle yanıt verebilir ve service_disabled değerini true olarak ayarlayabilir.

Kota hatasını işleme hakkında diğer ayrıntılar için RetryInfo ve Help türlerine de bakın.

Alanlar
violations[]

Violation

Tüm kota ihlallerini açıklar.

İhlal

Tek bir kota ihlalini açıklamak için kullanılan mesaj türü. Örneğin, günlük kota veya aşılan özel bir kota.

Alanlar
subject

string

Kota kontrolünün başarısız olduğu konu. Örneğin, "clientip:" veya "project:".
description

string

Kota kontrolünün neden başarısız olduğuna dair açıklama. Müşteriler, hizmetin herkese açık dokümanlarında kota yapılandırması hakkında daha fazla bilgi edinmek veya geliştirici konsolunda ayarlamak için ilgili kota sınırını bulmak üzere bu açıklamayı kullanabilir.

Örneğin: "Service disabled" (Hizmet devre dışı) veya "Daily Limit for read operations exceeded" (Okuma işlemleri için günlük sınır aşıldı).
api_service

string

QuotaFailure.Violation öğesinin kaynağı olan API hizmeti. Bazı durumlarda kota sorunları, çağrılan API hizmeti dışında bir API hizmetinden kaynaklanır. Başka bir deyişle, çağrılan API hizmetinin bağımlılığı QuotaFailure'nın nedeni olabilir ve bu alanda bağımlı API hizmetinin adı bulunur.

Örneğin, çağrılan API Kubernetes Engine API (container.googleapis.com) ise ve Kubernetes Engine API'nin kendisinde bir kota ihlali meydana gelirse bu alan "container.googleapis.com" olur. Öte yandan, kota ihlali Kubernetes Engine API, Compute Engine API'de (compute.googleapis.com) sanal makineler oluştururken gerçekleşirse bu alan "compute.googleapis.com" olur.
quota_metric

string

İhlal edilen kotanın metriği. Kota metriği, API istekleri veya CPU'lar gibi kullanımı ölçmek için adlandırılmış bir sayaçtır. Bir hizmette etkinlik gerçekleştiğinde (ör. sanal makine ayırma) bir veya daha fazla kota metriği etkilenebilir.

Örneğin, "compute.googleapis.com/cpus_per_vm_family", "storage.googleapis.com/internet_egress_bandwidth".
quota_id

string

İhlal edilen kotanın kimliği. "Limit adı" olarak da bilinen bu, bir API hizmeti bağlamındaki kotanın benzersiz tanımlayıcısıdır.

Örneğin, "CPUS-PER-VM-FAMILY-per-project-region".
quota_dimensions

map<string, string>

İhlal edilen kotanın boyutları. Küresel olmayan her kota, bir dizi boyutta uygulanır. Kota metriği neyin sayılacağını tanımlarken boyutlar, sayacın hangi yönler için artırılması gerektiğini belirtir.

Örneğin, "VM ailesi başına bölge başına CPU" kotası, "compute.googleapis.com/cpus_per_vm_family" metriği için "bölge" ve "vm_family" boyutlarında bir sınır uygular. İhlal "us-central1" bölgesinde ve "n1" sanal makine ailesi için gerçekleştiyse quota_dimensions şu şekilde olur:

{ "region": "us-central1", "vm_family": "n1", }

Kota genel olarak uygulandığında quota_dimensions her zaman boş olur.
quota_value

int64

QuotaFailure sırasında zorunlu kılınan kota değeri.

Örneğin, CPU sayısı için QuotaFailure sırasında zorunlu kılınan kota değeri "10" ise bu alanın değeri bu miktarı yansıtır.
future_quota_value

int64

İhlal sırasında kullanıma sunulan yeni kota değeri. Kullanıma sunma işlemi tamamlandığında bu değer, quota_value yerine zorunlu kılınır. İhlal sırasında kullanıma sunma işlemi devam etmiyorsa bu alan ayarlanmaz.

Örneğin, ihlal sırasında CPU sayısı kotasını 10'dan 20'ye değiştiren bir kullanıma sunma işlemi devam ediyorsa bu alanın değeri 20 olur.

RequestInfo

Müşterilerin hata bildirirken veya başka geri bildirimler sağlarken ekleyebileceği, istekle ilgili meta verileri içerir.

Alanlar
request_id

string

Yalnızca onu oluşturan hizmet tarafından yorumlanması gereken opak bir dize. Örneğin, hizmetin günlüklerindeki istekleri tanımlamak için kullanılabilir.
serving_data

string

Bu isteği karşılamak için kullanılan tüm veriler. Örneğin, hata ayıklama için hizmet sağlayıcıya geri gönderilebilen şifrelenmiş bir yığın izi.

ResourceInfo

Erişilen kaynağı açıklar.

Alanlar
resource_type

string

Erişilen kaynak türünün adı (ör. "sql tablosu", "cloud storage paketi", "dosya", "Google Takvim") veya kaynağın tür URL'si (ör. "type.googleapis.com/google.pubsub.v1.Topic").
resource_name

string

Erişilen kaynağın adı. Örneğin, paylaşılan bir takvim adı: "example.com_4fghdhgsrgh@group.calendar.google.com", mevcut hata google.rpc.Code.PERMISSION_DENIED ise.
owner

string

Kaynağın sahibi (isteğe bağlı). Örneğin, "user:" veya "project:".
description

string

Bu kaynağa erişilirken karşılaşılan hatayı açıklar. Örneğin, bir Cloud projesini güncellemek için geliştirici konsolu projesinde writer izni gerekebilir.

RetryInfo

İstemcilerin başarısız olan bir isteği ne zaman yeniden deneyebileceğini açıklar. İstemciler, bu bilgilerin hata yanıtlarında eksik olması durumunda öneriyi yoksayabilir veya yeniden deneyebilir.

İstemcilerin yeniden deneme yaparken her zaman eksponansiyel geri yükleme kullanması önerilir.

İstemciler, hata yanıtını aldıktan sonra retry_delay süre geçene kadar yeniden denememelidir. İstekleri yeniden deneme de başarısız olursa istemciler, retry_delay temelinde yeniden denemeler arasındaki gecikmeyi kademeli olarak artırmak için eksponansiyel geri yükleme şeması kullanmalıdır. Bu, maksimum yeniden deneme sayısına veya maksimum yeniden deneme gecikmesi sınırına ulaşılana kadar devam eder.

Alanlar
retry_delay

Duration

İstemciler, aynı isteği yeniden denemeden önce en az bu süre kadar beklemelidir.

Durum

Status türü, REST API'ler ve RPC API'ler dahil olmak üzere farklı programlama ortamlarına uygun mantıksal bir hata modeli tanımlar. gRPC tarafından kullanılır. Her Status mesajı; hata kodu, hata mesajı ve hata ayrıntıları olmak üzere üç veri içerir.

Bu hata modeli ve nasıl kullanılacağı hakkında daha fazla bilgiyi API Tasarım Kılavuzu'nda bulabilirsiniz.

Alanlar
code

int32

Durum kodu, google.rpc.Code enum değeri olmalıdır.
message

string

Geliştiriciye yönelik hata mesajı (İngilizce olmalıdır). Kullanıcıya gösterilen tüm hata mesajları yerelleştirilmiş olup google.rpc.Status.details alanında gönderilmeli veya istemci tarafından yerelleştirilmelidir.
details[]

Any

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