Cloud Firestore REST API verwenden

Am einfachsten lässt sich Cloud Firestore mit einer der native Clientbibliotheken verwenden, kann es in einigen Situationen nützlich sein, die REST API direkt aufrufen.

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

  • Sie können über eine ressourcenbeschränkte Umgebung auf Cloud Firestore zugreifen. wie z. B. ein IoT-Gerät, auf dem ein vollständiger Client ist nicht möglich.
  • 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. Bei diesen Anfragen Cloud Firestore verwendet Identity and Access Management (IAM), um festzustellen, -Anforderung 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.

Für Anfragen, die mit einem Firebase-ID-Token authentifiziert wurden, und für nicht authentifizierte Anfragen verwendet Cloud Firestore Ihre Cloud Firestore Security Rules, um festzustellen, ob eine Anfrage autorisiert wurde.

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 Bereich haben, um Anfragen an den Cloud Firestore REST API:

  • 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 von einem einzelnen Nutzer ausgeführt werden. Cloud Firestore Zulassungen um Ihre Sicherheitsregeln zu ignorieren. 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.

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, Die Cloud Firestore API gibt den HTTP-Statuscode 200 OK zurück und den die angeforderten Daten. Wenn eine Anfrage fehlschlägt, gibt die Cloud Firestore API eine HTTP-Statuscode 4xx oder 5xx und eine Antwort mit Informationen zu Fehler.

In der folgenden Tabelle sind für jeden Fehlercode empfohlene Aktionen aufgeführt. Es gelten diese Codes. an die REST API und die RPC API 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.