Cloud Firestore REST API'yi kullanma

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

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

  • Cloud Firestore'a, eksiksiz bir istemci kitaplığı çalıştırmanın mümkün olmadığı şeylerin interneti (IoT) cihazı gibi kaynak sınırlı 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 kullanma seçeneğini değerlendirin.

Kimlik doğrulama ve yetkilendirme

Cloud Firestore REST API, kimlik doğrulama için Firebase Authentication kimlik jetonu 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. Cloud Firestore, bu isteklerde isteğin yetkilendirilip yetkilendirilmediğini belirlemek için Cloud Firestore Güvenlik Kuralları'nı kullanır.

  • Uygulamanızdan gelen, veritabanı yönetimi istekleri gibi isteklerin kimliğini doğrulamak için Google Identity OAuth 2.0 jetonu ve hizmet hesabı kullanın. Cloud Firestore, bu istekler için bir isteğin yetkilendirilip yetkilendirilmediğini belirlemek için Identity and Access Management (IAM) yöntemini kullanır.

Firebase kimlik jetonlarıyla çalışma

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

Bir kullanıcının Firebase kimliği jetonunu alarak kullanıcı adına istek gönderebilirsiniz.

Cloud Firestore, Firebase kimlik jetonuyla kimliği doğrulanan istekler ve kimliği doğrulanmamış istekler için Cloud Firestore Güvenlik Kurallarınızı kullanarak isteğin yetkilendirilip yetkilendirilmediğini belirler.

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

Google API İstemci Kitaplığı ile birlikte bir hizmet hesabı kullanarak veya Sunucudan Sunucuya Uygulamalar için OAuth 2.0'ı Kullanma başlıklı makaledeki adımları uygulayarak erişim jetonu oluşturabilirsiniz. Ayrıca, gcloud komut satırı aracı ve gcloud auth application-default print-access-token komutuyla da jeton oluşturabilirsiniz.

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

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

İsteklerinizin kimliğini bir hizmet hesabı ve Google Identity OAuth 2.0 jetonu kullanarak doğrularsanız Cloud Firestore, isteklerinizin tek bir kullanıcı yerine uygulamanız adına hareket ettiğini varsayar. Cloud Firestore, bu isteklerin güvenlik kurallarınızı yoksaymasına olanak tanır. 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 Identity OAuth 2.0 jetonu aldıktan sonra bunu, Bearer {YOUR_TOKEN} olarak ayarlanmış bir Authorization üstbilgisi 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'sinin altında bulunur.

YOUR_PROJECT_ID projesi altındaki cities koleksiyonunda LA kimliğine sahip bir dokümana 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ş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 deneme yapmaya başlamanın en iyi yolu, otomatik olarak Google Identity OAuth 2.0 jetonları 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ına bakın veya API Gezgini'ni kullanın.

v1.projects.databases.documents

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

v1.projects.databases.collectionGroups.indexes

Dizinler üzerinde yeni dizinler oluşturma, mevcut bir dizini devre dışı bırakma veya tüm mevcut dizinleri listeleme gibi işlemler gerçekleştirin. 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 belge için tüm alanların ve alt koleksiyonların listesi gibi belge meta verilerinin alınmasını da sağlar.

Hata Kodları

Bir Cloud Firestore isteği başarılı olduğunda Cloud Firestore API, HTTP 200 OK durum kodu 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 listelenmiştir. 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.

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.