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ığı çalıştırmanın mümkün olmadığı şeylerin 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 kullanma seçeneğini değerlendirin.

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. Cloud Firestore, bu isteklerde bir isteğin yetkilendirilip yetkilendirilmediğini belirlemek için Cloud Firestore Security Rules değerini kullanır.

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

Firebase kimlik jetonlarıyla çalışma

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

• Firebase Authentication REST API'yi kullanarak bir Firebase kimlik jetonu oluşturun.
• Bir kullanıcının Firebase kimlik jetonunu Firebase Authentication SDK'sından alın.

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 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. 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'sinin 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 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 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.