Bu sayfa, Cloud Translation API ile çevrilmiştir.

Cloud Firestore REST API'sini kullanın

Cloud Firestore'u kullanmanın en kolay yolu yerel istemci kitaplıklarından birini kullanmak olsa da, doğrudan REST API'yi çağırmanın yararlı olduğu bazı durumlar da vardır.

REST API aşağıdaki kullanım durumları için yararlı olabilir:

Cloud Firestore'a, nesnelerin interneti (IoT) cihazı gibi, tam bir istemci kitaplığının çalıştırılmasının mümkün olmadığı, kaynak kısıtlı bir ortamdan erişme.
Veritabanı yönetimini otomatikleştirme veya ayrıntılı veritabanı meta verilerini alma.

GRPC destekli bir dil kullanıyorsanız REST API yerine RPC API'yi kullanmayı düşünün.

Kimlik doğrulama ve yetkilendirme

Kimlik doğrulama için Cloud Firestore REST API, Firebase Authentication ID jetonunu veya Google Identity OAuth 2.0 jetonunu kabul eder. Sağladığınız jeton, isteğinizin yetkilendirilmesini etkiler:

Uygulamanızın kullanıcılarından gelen isteklerin kimliğini doğrulamak için Firebase ID jetonlarını kullanın. Bu istekler için Cloud Firestore, bir isteğin yetkilendirilip yetkilendirilmediğini belirlemek amacıyla Cloud Firestore Güvenlik Kurallarını kullanır.
Uygulamanızdan gelen veritabanı yönetimi istekleri gibi isteklerin kimliğini doğrulamak için bir Google Identity OAuth 2.0 jetonu ve bir hizmet hesabı kullanın. Bu istekler için Cloud Firestore, bir isteğin yetkilendirilip yetkilendirilmediğini belirlemek amacıyla Kimlik ve Erişim Yönetimi'ni (IAM) kullanır.

Firebase ID jetonlarıyla çalışma

Firebase ID jetonunu iki şekilde elde edebilirsiniz:

Bir kullanıcının Firebase ID jetonunu alarak kullanıcı adına istekte bulunabilirsiniz.

Firebase ID belirteci ile kimliği doğrulanan istekler ve kimliği doğrulanmamış istekler için Cloud Firestore, bir isteğin yetkilendirilip yetkilendirilmediğini belirlemek için Cloud Firestore Güvenlik Kurallarınızı kullanır.

Google Identity OAuth 2.0 jetonlarıyla çalışma

Google API İstemci Kitaplığı'na sahip bir hizmet hesabı kullanarak veya Sunucudan Sunucuya Uygulamalar için OAuth 2.0'ı Kullanma bölümündeki adımları izleyerek bir erişim belirteci oluşturabilirsiniz. Ayrıca gcloud komut satırı aracını ve gcloud auth application-default print-access-token kullanarak da bir jeton oluşturabilirsiniz.

Bu belirtecin, Cloud Firestore REST API'ye istek göndermek için aşağıdaki kapsama sahip olması gerekir:

https://www.googleapis.com/auth/datastore

İsteklerinizi bir hizmet hesabı ve Google Identity OAuth 2.0 jetonuyla doğrularsanız Cloud Firestore, isteklerinizin bireysel bir kullanıcı yerine uygulamanız adına hareket ettiğini varsayar. Cloud Firestore, bu isteklerin güvenlik kurallarınızı göz ardı etmesine olanak tanır. Bunun yerine Cloud Firestore, bir isteğin yetkilendirilip yetkilendirilmediğini belirlemek için IAM'yi kullanır.

Cloud Firestore IAM rolleri atayarak hizmet hesaplarının erişim izinlerini kontrol edebilirsiniz.

Erişim belirteciyle kimlik doğrulama

Bir Firebase ID jetonu veya bir Google Identity OAuth 2.0 jetonu aldıktan sonra, bunu, Bearer {YOUR_TOKEN} olarak ayarlanmış bir Authorization başlığı olarak Cloud Firestore uç noktalarına iletin.

REST çağrıları yapma

Tüm REST API uç noktaları https://firestore.googleapis.com/v1/ temel URL'si altında bulunur.

YOUR_PROJECT_ID projesi kapsamındaki koleksiyon cities LA kimliğine sahip bir belgeye giden yol oluşturmak için aşağıdaki yapıyı kullanırsınız.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Bu yolla etkileşim kurmak için onu temel API URL'siyle birleştirin.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

REST API'yi denemeye başlamanın en iyi yolu, Google Identity OAuth 2.0 jetonlarını otomatik olarak oluşturan ve API'yi incelemenize olanak tanıyan API Explorer'ı kullanmaktır.

Yöntemler

Aşağıda en önemli iki yöntem grubunun kısa açıklamaları bulunmaktadır. Tam liste için REST API referansına bakın veya API Explorer'ı kullanın.

`v1.projects.databases.documents`

Veri ekleme veya veri alma kılavuzlarında belirtilenlere benzer şekilde belgeler üzerinde CRUD işlemleri gerçekleştirin.

`v1.projects.databases.collectionGroups.indexes`

Yeni dizinler oluşturmak, mevcut bir dizini devre dışı bırakmak veya mevcut tüm dizinleri listelemek gibi dizinler üzerinde eylemler gerçekleştirin. Veri yapısı geçişlerini otomatikleştirmek veya projeler arasında dizinleri senkronize etmek için kullanışlıdır.

Ayrıca belirli bir belgeye ilişkin tüm alanların ve alt koleksiyonların listesi gibi belge meta verilerinin alınmasına da olanak tanır.

Hata Kodları

Bir Cloud Firestore isteği başarılı olduğunda Cloud Firestore API, bir HTTP 200 OK durum kodunu ve istenen verileri döndürür. Bir istek başarısız olduğunda Cloud Firestore API, bir HTTP 4xx veya 5xx durum kodu ve hatayla ilgili bilgileri içeren bir yanıt döndürür.

Aşağıdaki tabloda her hata kodu için önerilen eylemler listelenmektedir. Bu kodlar Cloud Firestore REST ve RPC API'leri için geçerlidir. Cloud Firestore SDK'ları ve istemci kitaplıkları aynı hata kodlarını döndürmeyebilir.

Kanonik Hata Kodu	Tanım	Tavsiye edilen eylem
`ABORTED`	İstek başka bir istekle çakıştı.	İşlemsel olmayan bir taahhüt için: İsteği yeniden deneyin veya çekişmeyi azaltmak için veri modelinizi yeniden yapılandırın. Bir işlemdeki istekler için: Çekişmeyi azaltmak için işlemin tamamını yeniden deneyin veya veri modelinizi yeniden yapılandırın.
`ALREADY_EXISTS`	İstek, zaten var olan bir belgeyi oluşturmaya çalıştı.	Sorunu çözmeden tekrar denemeyin.
`DEADLINE_EXCEEDED`	İsteği işleyen Cloud Firestore sunucusu son tarihi aştı.	Üstel geri çekilmeyi kullanmayı yeniden deneyin.
`FAILED_PRECONDITION`	Talep, ön koşullarından birini karşılamadı. Örneğin, bir sorgu isteği henüz tanımlanmamış bir dizini gerektirebilir. Başarısız olan ön koşul için hata yanıtındaki mesaj alanına bakın.	Sorunu çözmeden tekrar denemeyin.
`INTERNAL`	Cloud Firestore sunucusu bir hata döndürdü.	Bu isteği bir kereden fazla tekrar denemeyin.
`INVALID_ARGUMENT`	Bir istek parametresi geçersiz bir değer içeriyor. Geçersiz değer için hata yanıtındaki mesaj alanına bakın.	Sorunu çözmeden tekrar denemeyin.
`NOT_FOUND`	İstek, mevcut olmayan bir belgeyi güncellemeye çalıştı.	Sorunu çözmeden tekrar denemeyin.
`PERMISSION_DENIED`	Kullanıcının bu istekte bulunma yetkisi yoktur.	Sorunu çözmeden tekrar denemeyin.
`RESOURCE_EXHAUSTED`	Proje ya kotasını ya da bölge/çoklu bölge kapasitesini aştı.	Proje kotanızı aşmadığınızı doğrulayın . Proje kotasını aştıysanız sorunu gidermeden tekrar denemeyin. Aksi takdirde, üstel geri çekilmeyle yeniden deneyin.
`UNAUTHENTICATED`	İstek, geçerli kimlik doğrulama bilgilerini içermiyordu.	Sorunu çözmeden tekrar denemeyin.
`UNAVAILABLE`	Cloud Firestore sunucusu bir hata döndürdü.	Üstel geri çekilmeyi kullanmayı yeniden deneyin.