Cloud Firestore REST API verwenden

Die einfachste Möglichkeit, Cloud Firestore zu verwenden, ist die Nutzung einer der nativen Clientbibliotheken. Es gibt jedoch 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 über eine ressourcenbeschränkte Umgebung, z. B. über ein IoT-Gerät, in dem eine vollständige Clientbibliothek nicht ausgeführt werden kann.
  • Datenbankadministration automatisieren oder detaillierte Datenbankmetadaten abrufen

Wenn Sie eine gRPC-unterstützte Sprache verwenden, sollten Sie die RPC API anstelle der REST API verwenden.

Authentifizierung und Autorisierung

Für die Authentifizierung akzeptiert die Cloud Firestore REST API entweder ein Firebase Authentication-ID-Token oder ein Google Identity OAuth 2.0-Token. Das verwendete Token hat Auswirkungen auf die Autorisierung der Anfrage:

  • Verwenden Sie Firebase-ID-Tokens, um Anfragen von Nutzern Ihrer Anwendung zu authentifizieren. Für diese Anfragen verwendet Cloud Firestore Cloud Firestore Security Rules, um festzustellen, ob eine Anfrage autorisiert ist.

  • Verwenden Sie ein Google Identity OAuth 2.0-Token und ein Dienstkonto, um Anfragen von Ihrer Anwendung zu authentifizieren, z. B. Anfragen zur Datenbankverwaltung. Für diese Anfragen verwendet Cloud Firestore die Identitäts- und Zugriffsverwaltung (IAM), um festzustellen, ob eine Anfrage autorisiert wurde.

Mit Firebase-ID-Token arbeiten

Sie haben zwei Möglichkeiten, ein Firebase-ID-Token zu erhalten:

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

Bei Anfragen, die mit einem Firebase-ID-Token authentifiziert wurden, und bei nicht authentifizierten Anfragen prüft Cloud Firestore anhand Ihrer Cloud Firestore Security Rules, ob eine Anfrage autorisiert ist.

Mit Google Identity OAuth 2.0-Tokens arbeiten

Sie können ein Zugriffstoken erstellen, indem Sie ein Dienstkonto mit einer Google API-Clientbibliothek verwenden oder die Schritte unter OAuth 2.0 für Server-zu-Server-Anwendungen verwenden ausführen. 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 Gültigkeitsbereich haben, um Anfragen an die Cloud Firestore REST API senden zu können:

  • 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 Nutzers ausgeführt werden. Mit Cloud Firestore werden bei solchen Anfragen Ihre Sicherheitsregeln ignoriert. Stattdessen verwendet Cloud Firestore IAM, um zu ermitteln, ob eine Anfrage autorisiert ist.

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

Mit einem Zugriffstoken authentifizieren

Nachdem Sie entweder ein Firebase-ID-Token oder ein Google Identity OAuth 2.0-Token abgerufen haben, übergeben Sie es an die Cloud Firestore-Endpunkte als Authorization-Header, für den Bearer {YOUR_TOKEN} festgelegt ist.

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 der Sammlung 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

Zur Interaktion mit diesem Pfad kombinieren Sie ihn mit der Basis-API-URL.

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

Die beste Möglichkeit, mit der REST API zu experimentieren, ist die Verwendung des API Explorer, der automatisch Google Identity OAuth 2.0-Token generiert und es Ihnen ermöglicht, die API zu untersuchen.

Methoden

Es folgt eine kurze Beschreibung der beiden wichtigsten Methodengruppen. Eine vollständige Liste finden Sie in der REST API-Referenz oder im API Explorer.

v1.projects.databases.documents

Führen Sie CRUD-Vorgänge für Dokumente aus, ähnlich wie in den Übersichten zu Daten hinzufügen oder Daten abrufen beschrieben.

v1.projects.databases.collectionGroups.indexes

Führen Sie Aktionen für Indexe wie das Erstellen neuer Indexe, das Deaktivieren eines vorhandenen Indexes oder das Auflisten aller aktuellen Indexe aus. Nützlich für die Automatisierung von Datenstrukturmigrationen oder die Synchronisierung von Indexen zwischen Projekten.

Ermöglicht auch den Abruf von Dokumentmetadaten, z. B. die Liste aller Felder und Untersammlungen für ein bestimmtes Dokument.

Fehlercodes

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

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

Kanonischer Fehlercode Beschreibung Empfohlene Maßnahme
ABORTED Die Anfrage steht in Konflikt mit einer anderen Anfrage. Bei einem nicht transaktionalen Commit:
Wiederholen Sie die Anfrage oder strukturieren Sie Ihr Datenmodell neu, um Konflikte zu reduzieren.

Bei Anfragen in einer Transaktion:
Wiederholen Sie die gesamte Transaktion oder strukturieren Sie Ihr Datenmodell neu, um Konflikte zu reduzieren.
ALREADY_EXISTS Die Anfrage hat versucht, ein Dokument zu erstellen, das bereits vorhanden ist. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
DEADLINE_EXCEEDED Der Cloud Firestore-Server, der die Anfrage verarbeitet, hat eine Frist überschritten. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
FAILED_PRECONDITION Die Anfrage hat eine der Voraussetzungen nicht erfüllt. Für eine Anfrage kann beispielsweise ein noch nicht definierter Index erforderlich sein. Sehen Sie sich das Nachrichtenfeld in der Fehlerantwort für die fehlgeschlagene Vorbedingung an. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
INTERNAL Der Cloud Firestore-Server hat einen Fehler zurückgegeben. Wiederholen Sie diese Anfrage nicht mehr als einmal.
INVALID_ARGUMENT Ein Anfrageparameter enthält einen ungültigen Wert. Sehen Sie sich das Nachrichtenfeld in der Fehlerantwort für den ungültigen Wert an. Wiederholen Sie die Anfrage erst dann, wenn das Problem behoben ist.
NOT_FOUND Die Anfrage hat versucht, ein Dokument zu aktualisieren, das nicht existiert. Wiederholen Sie die Anfrage erst dann, wenn das Problem behoben ist.
PERMISSION_DENIED Der Nutzer ist zu dieser Anfrage nicht berechtigt. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
RESOURCE_EXHAUSTED Das Projekt hat entweder das Kontingent oder die Kapazität der Region/Multiregion überschritten. Prüfen Sie, ob Sie Ihr Projektkontingent überschritten haben. Wenn Sie ein Projektkontingent überschritten haben, wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.

Versuchen Sie es andernfalls mit exponentiellem Backoff.
UNAUTHENTICATED Die Anfrage enthielt keine gültigen Anmeldedaten. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
UNAVAILABLE Der Cloud Firestore-Server hat einen Fehler zurückgegeben. Wiederholen Sie den Vorgang mit exponentiellem Backoff.