Firestore REST API verwenden

Die einfachste Möglichkeit zur Verwendung von Firestore ist die Verwendung einer der nativen Clientbibliotheken. Es gibt jedoch Situationen, in denen es nützlich ist, die REST API direkt aufzurufen.

Die REST API kann für folgende Anwendungsfälle nützlich sein:

  • Zugriff auf Firestore über eine ressourcenbeschränkte Umgebung, z. B. über ein IoT-Gerät, in dem keine vollständige Clientbibliothek ausgeführt werden kann.
  • Datenbankverwaltung automatisieren oder detaillierte Datenbankmetadaten abrufen

Wenn Sie eine gRPC-unterstützte Sprache verwenden, sollten Sie anstelle der REST API die RPC 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 von dir angegebene Token wirkt sich auf die Autorisierung deiner Anfrage aus:

  • Mit Firebase ID-Tokens können Sie Anfragen von den Nutzern Ihrer Anwendung authentifizieren. Für diese Anfragen verwendet Firestore Firestore-Sicherheitsregeln, um zu bestimmen, ob eine Anfrage autorisiert ist.

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

Mit Firebase-ID-Tokens 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 und bei nicht authentifizierten Anfragen authentifiziert wurden, bestimmt Firestore anhand Ihrer Firestore-Sicherheitsregeln, ob eine Anfrage autorisiert ist.

Mit OAuth-2.0-Tokens von Google Identity arbeiten

Sie können ein Zugriffstoken generieren, 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 Bereich haben, um Anfragen an die 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 Firestore davon aus, dass Ihre Anfragen im Namen Ihrer Anwendung und nicht eines einzelnen Nutzers ausgeführt werden. Mit Firestore können Ihre Anfragen diese Regeln ignorieren. Stattdessen verwendet Firestore IAM, um festzustellen, ob eine Anfrage autorisiert ist.

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

Mit einem Zugriffstoken authentifizieren

Nachdem Sie entweder ein Firebase-ID-Token oder ein Google Identity OAuth 2.0-Token erhalten haben, übergeben Sie es an die Firestore-Endpunkte als Authorization-Header, der auf Bearer {YOUR_TOKEN} gesetzt 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, verwenden Sie die folgende Struktur.

/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

Wenn Sie mit der REST API experimentieren möchten, sollten Sie am besten den API Explorer verwenden, der automatisch Google Identity OAuth 2.0-Tokens generiert und Ihnen die Prüfung der API ermöglicht.

Methoden

Im Folgenden finden Sie eine kurze Beschreibung der beiden wichtigsten Methodengruppen. Eine vollständige Liste finden Sie in der Referenz zur REST API oder verwenden den API Explorer.

v1.projects.databases.documents

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

v1.projects.databases.collectionGroups.indexes

Aktionen für Indexe ausführen, z. B. neue Indexe erstellen, vorhandene Indexe deaktivieren oder alle aktuellen Indexe auflisten 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 untergeordneten Sammlungen 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 und eine Antwort mit Informationen zum Fehler zurück.

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

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

Bei Anfragen in einer Transaktion:
Die gesamte Transaktion wiederholen oder Ihr Datenmodell neu strukturieren, um Konflikte zu reduzieren.
ALREADY_EXISTS Die Anfrage hat versucht, ein Dokument zu erstellen, das bereits vorhanden ist. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
DEADLINE_EXCEEDED Der Firestore-Server, der die Anfrage verarbeitet, hat eine Frist überschritten. Versuchen Sie es mit einem exponentiellen Backoff noch einmal.
FAILED_PRECONDITION Die Anfrage erfüllt eine der Voraussetzungen nicht. Für eine Abfrageanfrage kann beispielsweise ein noch nicht definierter Index erforderlich sein. Sehen Sie sich in der Fehlerantwort das Nachrichtenfeld für die fehlgeschlagene Vorbedingung an. Wiederholen Sie den Vorgang erst, 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. Das ungültige Feld wird in der Fehlerantwort im Nachrichtenfeld angezeigt. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
NOT_FOUND Die Anfrage hat versucht, ein Dokument zu aktualisieren, das nicht vorhanden ist. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
PERMISSION_DENIED Der Nutzer ist zu dieser Anfrage nicht berechtigt. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
RESOURCE_EXHAUSTED Das Projekt hat entweder sein Kontingent oder die Kapazität der Region bzw. Mehrfachregion überschritten. Prüfen, ob Sie Ihr Projektkontingent überschritten haben. Wenn Sie ein Projektkontingent überschritten haben, versuchen Sie es nicht noch einmal, ohne das Problem zu beheben.

Versuchen Sie es andernfalls mit exponentiellem Backoff.
UNAUTHENTICATED Die Anfrage enthielt keine gültigen Anmeldedaten für die Authentifizierung. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
UNAVAILABLE Der Firestore-Server hat einen Fehler zurückgegeben. Versuchen Sie es mit einem exponentiellen Backoff noch einmal.