Cloud Firestore REST API'yi kullanma

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

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

  • Tam bir istemci kitaplığının çalıştırılamadığı, kaynak kısıtlamalı bir ortamdan (ör. Nesnelerin İnterneti (IoT) cihazı) Cloud Firestore'ya erişme.
  • Veritabanı yönetimini otomatikleştirme veya ayrıntılı veritabanı meta verilerini alma

gRPC'yi destekleyen 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, isteğin yetkili olup olmadığını belirlemek üzere Cloud Firestore Security Rules kullanır.

  • Uygulamanızdan gelen isteklerin (ör. veritabanı yönetimi istekleri) kimliğini doğrulamak için Google Kimliği OAuth 2.0 jetonu ve hizmet hesabı kullanın. Bu istekler için, Cloud Firestore, bir isteğin yetkili olup olmadığını belirlemek için Kimlik ve Erişim Yönetimi'ni (IAM) kullanır.

Firebase kimlik jetonlarıyla çalışma

Firebase kimlik jetonunu iki şekilde elde edebilirsiniz:

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 yetkili olup olmadığını belirlemek üzere Cloud Firestore Security Rules kullanır.

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

Google API İstemci Kitaplığı ile 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. 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 kapsamda olması gerekir:

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

İsteklerinizin kimliğini bir hizmet hesabı ve Google Kimliği OAuth 2.0 jetonu ile doğruluyorsanız Cloud Firestore, isteklerinizin bireysel bir kullanıcı yerine uygulamanız adına hareket ettiğini varsayar. Cloud Firestore, bu isteklerin güvenlik kurallarınızı yoksaymasına izin verir. Bunun yerine, Cloud Firestore bir isteğin yetkili olup olmadığını belirlemek için IAM'yi 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 üstbilgisi olarak iletin.

REST çağrıları yapma

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

YOUR_PROJECT_ID projesi altındaki cities koleksiyonunda LA kimlikli bir dokümana giden 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'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 dizinler oluşturma, mevcut bir dizini devre dışı bırakma veya tüm mevcut dizinleri listeleme gibi dizinlerle ilgili işlemleri gerçekleştirin. Veri yapısı taşımalarını otomatikleştirmek veya projeler arasında dizinleri senkronize etmek için kullanışlıdır.

Ayrıca, belirli bir dokümana ait tüm alanların ve alt koleksiyonların listesi gibi doküman meta verilerinin alınmasını sağlar.

Hata Kodları

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 4xx veya 5xx HTTP 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 FirestoreSDK'lar ve istemci kitaplıkları bu hata kodlarını döndürmeyebilir.

Canonical Error Code Açıklama Önerilen işlem
ABORTED İstek başka bir istekle çakıştı. İşlem içermeyen bir commit için:
İsteği yeniden deneyin veya çekişmeyi azaltmak için veri modelinizi yeniden yapılandırın.

İş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üklemeyle 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 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 ileti 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 isteği göndermeye 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. Bir proje kotasını aştıysanız sorunu düzeltmeden yeniden denemeyin.

Aksi takdirde, eksponansiyel geri yükleme ile yeniden 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üklemeyle yeniden deneyin.