Verwenden Sie die Cloud Firestore-REST-API

Während der einfachste Weg, Cloud Firestore zu nutzen, darin besteht, eine der nativen Client-Bibliotheken zu verwenden, gibt es Situationen, in denen es sinnvoll ist, die REST-API direkt aufzurufen.

Die REST-API kann für die folgenden Anwendungsfälle hilfreich sein:

  • Zugriff auf Cloud Firestore aus einer ressourcenbeschränkten Umgebung, z. B. einem Internet-of-Things-Gerät (IoT), wo die Ausführung einer vollständigen Client-Bibliothek nicht möglich ist.
  • Automatisierung der Datenbankverwaltung oder Abrufen detaillierter Datenbankmetadaten.

Wenn Sie eine von gRPC unterstützte Sprache verwenden, sollten Sie die Verwendung der RPC-API anstelle der REST-API in Betracht ziehen.

Authentifizierung und Autorisierung

Zur Authentifizierung akzeptiert die Cloud Firestore REST API entweder ein Firebase-Authentifizierungs- ID-Token oder ein Google Identity OAuth 2.0- Token. Das von Ihnen bereitgestellte Token wirkt sich auf die Autorisierung Ihrer Anfrage aus:

  • Verwenden Sie Firebase-ID-Tokens, um Anfragen von den Benutzern Ihrer Anwendung zu authentifizieren. Für diese Anfragen verwendet Cloud Firestore Cloud Firestore-Sicherheitsregeln , um zu bestimmen, ob eine Anfrage autorisiert ist.

  • Verwenden Sie ein Google Identity OAuth 2.0-Token und ein Dienstkonto , um Anfragen von Ihrer Anwendung zu authentifizieren, beispielsweise Anfragen zur Datenbankverwaltung. Für diese Anfragen verwendet Cloud Firestore Identity and Access Management (IAM) , um zu bestimmen, ob eine Anfrage autorisiert ist.

Arbeiten mit Firebase-ID-Tokens

Sie können ein Firebase-ID-Token auf zwei Arten erhalten:

Durch Abrufen des Firebase-ID-Tokens eines Benutzers können Sie Anfragen im Namen des Benutzers stellen.

Bei Anfragen, die mit einem Firebase-ID-Token authentifiziert wurden, und bei nicht authentifizierten Anfragen verwendet Cloud Firestore Ihre Cloud Firestore-Sicherheitsregeln , um zu bestimmen, ob eine Anfrage autorisiert ist.

Arbeiten mit Google Identity OAuth 2.0-Tokens

Sie können ein Zugriffstoken generieren, indem Sie ein Dienstkonto mit einer Google API-Clientbibliothek verwenden oder indem Sie die Schritte unter „Verwenden von OAuth 2.0 für Server-zu-Server-Anwendungen“ befolgen. Sie können ein Token auch mit dem gcloud -Befehlszeilentool und dem Befehl gcloud auth application-default print-access-token generieren.

Dieses Token muss den folgenden Bereich haben, um Anfragen an die Cloud Firestore REST API zu senden:

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

Wenn Sie Ihre Anfragen mit einem Dienstkonto und einem Google Identity OAuth 2.0-Token authentifizieren, geht Cloud Firestore davon aus, dass Ihre Anfragen im Namen Ihrer Anwendung und nicht im Namen eines einzelnen Benutzers erfolgen. Cloud Firestore lässt zu, dass diese Anfragen Ihre Sicherheitsregeln ignorieren. Stattdessen verwendet Cloud Firestore IAM , um zu bestimmen, ob eine Anfrage autorisiert ist.

Sie können die Zugriffsberechtigungen von Dienstkonten steuern, indem Sie Cloud Firestore IAM-Rollen zuweisen.

Authentifizierung mit einem Zugriffstoken

Nachdem Sie entweder ein Firebase-ID-Token oder ein Google Identity OAuth 2.0-Token erhalten haben, übergeben Sie es als Authorization mit dem Wert Bearer {YOUR_TOKEN} an die Cloud Firestore-Endpunkte.

REST-Aufrufe durchführen

Alle REST-API-Endpunkte sind unter der Basis-URL https://firestore.googleapis.com/v1/ vorhanden.

Um einen Pfad zu einem Dokument mit der ID LA in den cities unter dem Projekt YOUR_PROJECT_ID zu erstellen, würden Sie die folgende Struktur verwenden.

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

Um mit diesem Pfad zu interagieren, kombinieren Sie ihn mit der Basis-API-URL.

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

Der beste Weg, mit dem Experimentieren mit der REST-API zu beginnen, ist die Verwendung des API Explorers , der automatisch Google Identity OAuth 2.0-Tokens generiert und es Ihnen ermöglicht, die API zu untersuchen.

Methoden

Nachfolgend finden Sie kurze Beschreibungen der beiden wichtigsten Methodengruppen. Eine vollständige Liste finden Sie in der REST-API-Referenz oder verwenden Sie den API Explorer .

v1.projects.databases.documents

Führen Sie CRUD-Vorgänge für Dokumente durch, ähnlich den in den Anleitungen zum Hinzufügen von Daten oder Abrufen von Daten beschriebenen.

v1.projects.databases.collectionGroups.indexes

Führen Sie Aktionen für Indizes durch, z. B. das Erstellen neuer Indizes, das Deaktivieren eines vorhandenen Indexes oder das Auflisten aller aktuellen Indizes. Nützlich für die Automatisierung von Datenstrukturmigrationen oder die Synchronisierung von Indizes zwischen Projekten.

Ermöglicht außerdem den Abruf von Dokumentmetadaten, z. B. der Liste aller Felder und Untersammlungen für ein bestimmtes Dokument.

Fehlercodes

Wenn eine Cloud Firestore-Anfrage erfolgreich ist, gibt die Cloud Firestore-API einen HTTP- 200 OK Statuscode und die angeforderten Daten zurück. Wenn eine Anfrage fehlschlägt, gibt die Cloud Firestore API einen HTTP 4xx oder 5xx Statuscode und eine Antwort mit Informationen zum Fehler zurück.

In der folgenden Tabelle sind die empfohlenen Maßnahmen für jeden Fehlercode aufgeführt. Diese Codes gelten für die Cloud Firestore REST- und RPC-APIs. Die Cloud Firestore SDKs und Clientbibliotheken geben möglicherweise nicht dieselben Fehlercodes zurück.

Kanonischer Fehlercode Beschreibung Empfohlene Maßnahme
ABORTED Die Anfrage stand im Konflikt mit einer anderen Anfrage. Für einen nicht-transaktionalen Commit:
Wiederholen Sie die Anfrage oder strukturieren Sie Ihr Datenmodell neu, um Konflikte zu reduzieren.

Für Anfragen in einer Transaktion:
Wiederholen Sie die gesamte Transaktion oder strukturieren Sie Ihr Datenmodell neu, um Konflikte zu reduzieren.
ALREADY_EXISTS Bei der Anfrage wurde versucht, ein bereits vorhandenes Dokument zu erstellen. Versuchen Sie es nicht erneut, ohne das Problem zu beheben.
DEADLINE_EXCEEDED Der Cloud Firestore-Server, der die Anfrage verarbeitet, hat eine Frist überschritten. Versuchen Sie es erneut mit exponentiellem Backoff.
FAILED_PRECONDITION Der Antrag erfüllte eine seiner Voraussetzungen nicht. Beispielsweise könnte eine Abfrageanforderung einen Index erfordern, der noch nicht definiert ist. Sehen Sie sich das Nachrichtenfeld in der Fehlerantwort für die fehlgeschlagene Vorbedingung an. Versuchen Sie es nicht erneut, ohne das Problem zu beheben.
INTERNAL Der Cloud Firestore-Server hat einen Fehler zurückgegeben. Wiederholen Sie diese Anfrage nicht mehr als einmal.
INVALID_ARGUMENT Ein Anforderungsparameter enthält einen ungültigen Wert. Den ungültigen Wert finden Sie im Nachrichtenfeld in der Fehlerantwort. Versuchen Sie es nicht erneut, ohne das Problem zu beheben.
NOT_FOUND Bei der Anfrage wurde versucht, ein Dokument zu aktualisieren, das nicht vorhanden ist. Versuchen Sie es nicht erneut, ohne das Problem zu beheben.
PERMISSION_DENIED Der Benutzer ist nicht berechtigt, diese Anfrage zu stellen. Versuchen Sie es nicht erneut, ohne das Problem zu beheben.
RESOURCE_EXHAUSTED Das Projekt hat entweder sein Kontingent oder die regionale/multiregionale Kapazität überschritten. Stellen Sie sicher, dass Sie Ihr Projektkontingent nicht überschritten haben . Wenn Sie ein Projektkontingent überschritten haben, versuchen Sie es nicht erneut, ohne das Problem zu beheben.

Andernfalls versuchen Sie es erneut mit exponentiellem Backoff.
UNAUTHENTICATED Die Anfrage enthielt keine gültigen Authentifizierungsdaten. Versuchen Sie es nicht erneut, ohne das Problem zu beheben.
UNAVAILABLE Der Cloud Firestore-Server hat einen Fehler zurückgegeben. Versuchen Sie es erneut mit exponentiellem Backoff.