Cloud Firestore REST API'yi kullanma

Cloud Firestore 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 ürününe kaynak açısından sınırlı 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

Kimlik doğrulama için Cloud Firestore REST API, Firebase Authentication kimlik jetonunu veya Google Identity OAuth 2.0 jetonunu kabul eder. 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. Bu istekler için Cloud Firestore, bir isteğin yetkilendirilmiş olup olmadığını belirlemek üzere Cloud Firestore Security Rules kullanır.

  • Google Identity OAuth 2.0 jetonu ve bir hizmet hesabınızı kullanarak (veritabanı yönetimi istekleri gibi) Bu istekler için Cloud Firestore, isteğin yetkilendirilmiş olup olmadığını belirlemek amacıyla Kimlik ve Erişim Yönetimi (IAM)'ni kullanır.

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 Bir isteğin olup olmadığını belirlemek için Cloud Firestore Security Rules 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 jeton, Cloud Firestore REST API'ye istek göndermek için aşağıdaki kapsama sahip olmalıdır:

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

İsteklerinizde kimlik doğrulamasını bir hizmet hesabı ve Google Kimlik OAuth 2.0 jetonuyla yaparsanız Cloud Firestore, isteklerinizin bireysel bir kullanıcı yerine uygulamanız adına yapıldığını varsayar. Cloud Firestore, bu isteklerin güvenlik kurallarınızı yoksaymasına izin verir. 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 jetonu kullanıyorsanız, kodu Cloud Firestore uç noktalarına Authorization 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

Dizinlerde yeni dizin oluşturma, mevcut bir dizini devre dışı bırakma veya mevcut tüm dizinleri listeleme gibi işlemler gerçekleştirebilir. Veri yapısı taşıma işlemlerini otomatikleştirmek veya dizinleri projeler arasında senkronize etmek için kullanışlıdır.

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ı

Bir Cloud Firestore isteği başarılı olduğunda Cloud Firestore API, bir 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 geçiş yapabilirsiniz. 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 sunucusunun son tarihi geçti. Eksponansiyel geri yükleme yöntemini kullanmayı yeniden deneyin.
FAILED_PRECONDITION İstek, ön koşullarından birini karşılamıyor. Örneğin, bir sorgu isteği henüz tanımlanmayan bir dizin gerektirebilir. Başarısız olan ön koşulun 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 isteği gönderme 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 kullanarak yeniden deneyin.