Cloud Firestore REST API'yi kullanma

Cloud Firestore'u kullanmanın en kolay yolu bazı durumlarda, yerel istemci kitaplıklarının doğrudan REST API'ye çağrıda bulunur.

REST API aşağıdaki kullanım alanlarında faydalı olabilir:

  • Cloud Firestore'a kaynak kısıtlamalı bir ortamdan erişmek, ör. eksiksiz bir istemcinin çalıştırıldığı, nesnelerin interneti (IoT) cihazı mümkün değildir.
  • Veritabanı yönetimini otomatikleştirme veya ayrıntılı veritabanı meta verilerini alma.

Bir gRPC destekli dil kullanıyorsanız REST API yerine RPC API.

Kimlik doğrulama ve yetkilendirme

Cloud Firestore REST API, kimlik doğrulama için Firebase Authentication kimlik jetonu veya Google Identity OAuth 2.0 jetonu. Sağladığınız jeton isteğinizin yetkilendirmesini etkiler:

  • Uygulamanızın kullanıcılarından gelen isteklerin kimliğini doğrulamak için Firebase kimlik jetonlarını kullanın. Cloud Firestore, bu istekler için Talebin karşılanıp karşılanmadığını belirlemek için Cloud Firestore Güvenlik Kuralları yetkilidir.

  • Google Identity OAuth 2.0 jetonu ve bir hizmet hesabınızı kullanarak (veritabanı yönetimi istekleri gibi) Bu talepler için Cloud Firestore Identity and Access Management (IAM) üzerinden yetkilendirilmiş olması gerekir.

Firebase kimlik jetonlarıyla çalışma

Firebase kimlik jetonu almak için iki yöntem vardır:

Kullanıcının Firebase kimliği jetonunu alarak belirtir.

Firebase kimlik jetonuyla kimliği doğrulanmış ve kimliği doğrulanmamış istekler için istekleri için Cloud Firestore Cloud Firestore Güvenlik Kuralları'nı kullanarak bir isteğin yetkilendirildi.

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

Bir hizmet hesabını Google API İstemci Kitaplığı veya Sunucudan Sunucuya Uygulamalar için OAuth 2.0 Kullanma. Siz gcloud komut satırı aracı ve gcloud auth application-default print-access-token komutunu girin.

Bu jetonun, Cloud Firestore REST API:

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

İsteklerinizin kimliğini bir hizmet hesabı ve Google Kimliği ile yapıyorsanız OAuth 2.0 jetonu, Cloud Firestore, isteklerinizin onun adına işlem yaptığını varsayar uygulamanızı sağlar. Cloud Firestore, bu isteklerin güvenlik kurallarınızı yoksaymasını sağlayın. Bunun yerine, Cloud Firestore bir isteğin yetkilendirilip yetkilendirilmediğini belirlemek için IAM'yi kullanır.

Hizmet hesaplarının erişim izinlerini kontrol etmek için Cloud Firestore IAM rolleri.

Erişim jetonuyla kimlik doğrulama

Firebase kimlik jetonu veya Google Identity OAuth 2.0 jetonu aldıktan sonra bir Authorization jetonu olarak Cloud Firestore uç noktalarına geçirin. başlık Bearer {YOUR_TOKEN} olarak ayarlandı.

REST çağrıları yapma

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

cities koleksiyonundaki LA kimliğine sahip bir dokümana yol oluşturmak için YOUR_PROJECT_ID projesi altında aşağıdaki yapıyı kullanırsınız.

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

Bu yolla etkileşimde bulunmak için yolu temel API URL'si ile birleştirin.

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

REST API ile denemelere başlamanın en iyi yolu Otomatik olarak Google Kimliği oluşturan API Gezgini OAuth 2.0 jetonları ve API'yi incelemenize olanak tanır.

Yöntemler

Aşağıda, en önemli iki yöntem grubunun kısa açıklamaları verilmiştir. Eksiksiz bir REST API referansına bakın veya API Gezgini'ni kullanın.

v1.projects.databases.documents

Dokümanlar üzerinde, şurada belirtilenlere benzer CRUD işlemleri gerçekleştirin: veri ekleyin veya veri alma kılavuzlarını inceleyin.

v1.projects.databases.collectionGroups.indexes

Dizinler üzerinde yeni dizin oluşturma, mevcut bir dizini devre dışı bırakma gibi işlemler gerçekleştirin dizine ekleyebilir veya mevcut tüm dizinleri listeleyebilirsiniz. Veri yapısını otomatikleştirmek için kullanışlıdır taşıma veya dizinleri projeler arasında senkronize etme.

Ayrıca tüm belgelerin listesi gibi doküman meta verilerinin alınmasını da sağlar alanları ve alt koleksiyonları içerir.

Hata Kodları

Cloud Firestore isteği başarılı olduğunda Cloud Firestore API, HTTP 200 OK durum kodu döndürür ve isteyeceğiz. Bir istek başarısız olduğunda Cloud Firestore API, HTTP 4xx veya 5xx durum kodu ve hakkında bilgi içeren bir yanıt gösterir.

Aşağıdaki tabloda, her hata kodu için önerilen işlemler listelenmiştir. Bu kodlar geçerlidir Cloud Firestore REST ve RPC API'lerine bağlayabilirsiniz. Cloud Firestore SDK'lar ve istemci kitaplıkları aynı hata kodlarını döndürmeyebilir.

Standart Hata Kodu Açıklama Önerilen işlem
ABORTED Talep, başka bir taleple çakıştı. İşlem dışı bir kaydetme işlemi 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:
İşlemin tamamını yeniden deneyin veya veri modelinizi yeniden yapılandırarak çakışmayı azaltın.
ALREADY_EXISTS İstek, zaten mevcut olan bir dokümanı oluşturmaya çalıştı. Sorunu düzeltmeden tekrar denemeyin.
DEADLINE_EXCEEDED İsteği işleyen Cloud Firestore sunucusu belirlenen bir son tarihi aştı. Eksponansiyel geri yükleme yöntemini kullanmayı yeniden deneyin.
FAILED_PRECONDITION İstek, ön koşullarından birini karşılamadı. Örneğin, bir sorgu isteği henüz tanımlanmayan bir dizin gerektirebilir. Başarısız olan ön koşul için hata yanıtındaki mesaj alanına bakın. Sorunu düzeltmeden tekrar denemeyin.
INTERNAL Cloud Firestore sunucusu hata döndürdü. Bu isteği bir defadan fazla tekrarlamayın.
INVALID_ARGUMENT Bir istek parametresi geçersiz bir değer içeriyor. Geçersiz değeri, hata yanıtındaki mesaj alanında bulabilirsiniz. Sorunu düzeltmeden tekrar denemeyin.
NOT_FOUND İstek, mevcut olmayan bir dokümanı güncellemeye çalıştı. Sorunu düzeltmeden tekrar denemeyin.
PERMISSION_DENIED Kullanıcının bu istekte bulunma yetkisi yok. Sorunu düzeltmeden tekrar denemeyin.
RESOURCE_EXHAUSTED Proje kotasını veya bölge/çok bölgeli kapasitesini aştı. Proje kotanızı aşmadığınızı doğrulayın. Proje kotasını aştıysanız sorunu düzeltmeden tekrar denemeyin.

Aksi takdirde eksponansiyel geri yükleme ile tekrar deneyin.
UNAUTHENTICATED İstek geçerli kimlik doğrulama bilgileri içermiyordu. Sorunu düzeltmeden tekrar denemeyin.
UNAVAILABLE Cloud Firestore sunucusu hata döndürdü. Eksponansiyel geri yükleme yöntemini kullanmayı yeniden deneyin.