Firestore REST API verwenden

Die einfachste Möglichkeit der Anwendung von Firestore ist die Nutzung der nativen Clientbibliotheken. In manchen Situationen kann es aber sinnvoll sein, die REST API direkt aufzurufen.

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

  • Zugriff auf Firestore über eine ressourcenbeschränkte Umgebung, z. B. über ein IoT-Gerät, in dem eine komplette Clientbibliothek nicht ausgeführt werden kann.
  • Automatisierung der Datenbankverwaltung oder Abruf detaillierter Datenbankmetadaten.

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 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 nutzt Firestore Firestore-Sicherheitsregeln, um zu ermitteln, 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 Firestore die Identitäts- und Zugriffsverwaltung (IAM), um zu ermitteln, ob eine Anfrage autorisiert ist.

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 Firestore anhand Ihrer Firestore-Sicherheitsregeln, 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 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 Firestore davon aus, dass Ihre Anfragen im Auftrag Ihrer Anwendung und nicht eines einzelnen Nutzers gesendet werden. Mit Firestore werden bei solchen Anfragen Ihre Sicherheitsregeln ignoriert. Stattdessen verwendet Firestore IAM, um zu ermitteln, ob eine Anfrage autorisiert ist.

Sie können die Zugriffsberechtigungen von Dienstkonten durch Zuweisen von Firestore-IAM-Rollen steuern.

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 Firestore-Endpunkte als Authorization-Header, für den Bearer {YOUR_TOKEN} festgelegt ist.

REST-Aufrufe ausfü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 Firestore-Anfrage erfolgreich ist, gibt die Firestore API den HTTP-Statuscode 200 OK und die angeforderten Daten zurück. Wenn eine Anfrage fehlschlägt, gibt die Firestore API den 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 API und die RPC API von Firestore. Bei den Firestore SDKs und Clientbibliotheken werden möglicherweise andere Fehlercodes zurückgegeben.

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 die Anfrage erst dann, wenn das Problem behoben ist.
DEADLINE_EXCEEDED Der 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 die Anfrage erst dann, wenn das Problem behoben ist.
INTERNAL Der Firestore-Server hat einen Fehler zurückgegeben. Wiederholen Sie diese Anfrage nur 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 die Anfrage erst dann, 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 die Anfrage erst dann, wenn das Problem behoben ist.
UNAVAILABLE Der Firestore-Server hat einen Fehler zurückgegeben. Wiederholen Sie den Vorgang mit exponentiellem Backoff.