Cloud Firestore REST API'yi kullanma

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

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

  • Tam bir istemci kitaplığının çalıştırılmasının mümkün olmadığı, nesnelerin interneti (IoT) cihazı gibi kaynak kısıtlaması olan bir ortamdan Cloud Firestore'e 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üşünebilirsiniz.

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.

  • Uygulamanızdan gelen istekler (ör. veritabanı yönetimi istekleri) için kimlik doğrulaması yapmak üzere bir Google Identity OAuth 2.0 jetonu ve hizmet hesabı kullanın. 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 jetonunu iki şekilde edinebilirsiniz:

Kullanıcının Firebase kimlik jetonunu alarak kullanıcı adına istek gönderebilirsiniz.

Cloud Firestore, Firebase kimlik jetonuyla kimliği doğrulanmış istekler ve kimliği doğrulanmamış istekler için bir isteğin yetkilendirilmiş olup olmadığını belirlemek üzere Cloud Firestore Security Rules kimliğinizi kullanır.

Google Kimliği OAuth 2.0 jetonlarıyla çalışma

Google API istemci kitaplığı ile bir hizmet hesabı kullanarak veya Sunucudan Sunucuya Uygulamalar için OAuth 2.0'ı kullanma bölümündeki adımları uygulayarak erişim jetonu oluşturabilirsiniz. gcloud komut satırı aracını ve gcloud auth application-default print-access-token komutunu kullanarak da jeton oluşturabilirsiniz.

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'ı kullanır.

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

Erişim jetonuyla kimlik doğrulama

Bir Firebase kimlik jetonu veya Google Kimliği OAuth 2.0 jetonu aldıktan sonra, Bearer {YOUR_TOKEN} olarak ayarlanmış bir Authorization üstbilgisi olarak Cloud Firestore uç noktalarına iletin.

REST çağrısı yapma

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

YOUR_PROJECT_ID projesi kapsamındaki cities koleksiyonunda LA kimlikli bir dokümanın yolunu oluşturmak için aşağıdaki yapıyı kullanırsınız.

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

Bu yola erişmek için 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 Gezgini'ni kullanmaktır.

Yöntemler

Aşağıda, en önemli iki yöntem grubunun kısa açıklamaları verilmiştir. Tam liste için REST API referansı bölümüne bakın veya API Gezgini'ni kullanın.

v1.projects.databases.documents

Veri ekleme veya Veri alma kılavuzlarında açıklananlara benzer şekilde, dokümanlar üzerinde CRUD işlemleri gerçekleştirin.

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, belirli bir dokümanla ilgili tüm alanların ve alt koleksiyonların listesi gibi doküman meta verilerinin de alınmasına olanak tanır.

Hata Kodları

Bir Cloud Firestore isteği başarılı olduğunda Cloud Firestore API, HTTP 200 OK durum kodunu ve istenen verileri döndürür. Bir istek başarısız olduğunda Cloud Firestore API, 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 işlemler 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.

Kurallı Hata Kodu Açıklama Önerilen işlem
ABORTED İstek başka bir istekle çakışıyordu. İşlemsel olmayan bir taahhüt için:
İsteği yeniden deneyin veya anlaşmazlığı azaltmak için veri modelinizi yeniden yapılandırın.

İşlemdeki istekler için:
İşlemin tamamını yeniden deneyin veya anlaşmazlığı azaltmak için veri modelinizi yeniden yapılandırı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, son tarihi aştı. Eksponansiyel geri yükleme kullanarak yeniden deneyin.
FAILED_PRECONDITION İstek, ön koşullarından birini karşılamıyor. Örneğin, bir sorgu isteği henüz tanımlanmamış 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ürmüştür. Bu isteği birden fazla kez 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 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/çoklu bölge kapasitesini aştı. Proje kotanızı aşmadığınızı doğrulayın. Bir proje kotasını aştıysanız sorunu düzeltmeden yeniden denemeyin.

Aksi takdirde, eksponansiyel geri yüklemeyle yeniden deneyin.
UNAUTHENTICATED İstek geçerli kimlik doğrulama kimlik bilgilerini içermiyordu. Sorunu düzeltmeden tekrar denemeyin.
UNAVAILABLE Cloud Firestore sunucusu hata döndürmüştür. Eksponansiyel geri yükleme kullanarak yeniden deneyin.