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ında faydalı olabilir:

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

Kimlik doğrulama ve yetkilendirme

Cloud Firestore REST API, kimlik doğrulama için 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, isteğin yetkilendirilip yetkilendirilmediğini belirlemek üzere Cloud Firestore Security Rules kullanır.

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

Firebase kimlik jetonlarıyla çalışma

Firebase kimlik jetonunu iki şekilde alabilirsiniz:

Kullanıcının Firebase kimlik jetonunu alarak kullanıcı adına istekte bulunabilirsiniz.

Firebase kimlik jetonuyla kimliği doğrulanmış istekler ve kimliği doğrulanmamış istekler için Cloud Firestore, bir isteğin yetkilendirilip yetkilendirilmediğini belirlemek üzere Cloud Firestore Security Rules'nizi kullanır.

Google Identity 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 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öndermek 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 ile doğrularsanız Cloud Firestore, isteklerinizin bireysel bir kullanıcı yerine uygulamanız adına işlem yaptığı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'i kullanır.

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

Erişim jetonuyla kimlik doğrulama

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

REST çağrıları yapma

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

YOUR_PROJECT_ID projesindeki cities koleksiyonunda LA kimliğine sahip 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 yolla etkileşim kurmak için temel API URL'siyle birleştirin.

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

REST API ile denemeler yapmaya 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ına bakın veya API Gezgini'ni kullanın.

v1.projects.databases.documents

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

v1.projects.databases.collectionGroups.indexes

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

Ayrıca, belirli bir dokümanın tüm alanlarının ve alt koleksiyonlarının listesi gibi doküman 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 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 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ı bu hata kodlarını döndürmeyebilir.

Standart hata kodu Açıklama Önerilen işlem
ABORTED İstek başka bir istekle çakıştı. İşlemsel olmayan bir commit 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 çekişmeyi 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şılamadı. Örneğin, bir sorgu isteği henüz tanımlanmamış 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 bir hata döndürdü. Bu isteği birden fazla kez yeniden 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ı bu istekte bulunmaya yetkili değil. 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. 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çermiyor. Sorunu düzeltmeden tekrar denemeyin.
UNAVAILABLE Cloud Firestore sunucusu bir hata döndürdü. Eksponansiyel geri yükleme kullanarak yeniden deneyin.