Używanie interfejsu Cloud Firestore API typu REST

Najłatwiejszym sposobem korzystania z Cloud Firestore jest użycie jednej z natywnych bibliotek klienta, ale w niektórych sytuacjach przydatne może być bezpośrednie wywoływanie interfejsu API REST.

Interfejs API REST może być przydatny w tych przypadkach:

  • Uzyskiwanie dostępu do Cloud Firestore ze środowiska o ograniczonych zasobach, np. z urządzenia internetu rzeczy (IoT), na którym nie można uruchomić pełnej biblioteki klienta .
  • Automatyzacja administrowania bazą danych lub pobieranie szczegółowych metadanych bazy danych.

Jeśli używasz języka obsługującego gRPC, rozważ użycie interfejsu RPC API zamiast interfejsu REST API.

Uwierzytelnianie i autoryzacja

Do uwierzytelniania interfejs Cloud Firestore REST API akceptuje token identyfikatora Firebase Authentication lub token Google Identity OAuth 2.0. Podany token wpływa na autoryzację żądania:

  • Używaj tokenów identyfikatora Firebase do uwierzytelniania żądań od użytkowników aplikacji. W przypadku tych żądań Cloud Firestore używa Cloud Firestore Security Rules, aby określić, czy żądanie jest autoryzowane.

  • Używaj tokena Google Identity OAuth 2.0 i konta usługi do uwierzytelniania żądań z aplikacji, np. żądań dotyczących administrowania bazą danych. W przypadku tych żądań, Cloud Firestore używa Identity and Access Management (IAM) aby określić, czy żądanie jest autoryzowane.

Praca z tokenami identyfikatora Firebase

Token identyfikatora Firebase możesz uzyskać na 2 sposoby:

Pobierając token identyfikatora Firebase użytkownika, możesz wysyłać żądania w jego imieniu.

W przypadku żądań uwierzytelnionych za pomocą tokena identyfikatora Firebase oraz żądań nieuwierzytelnionych Cloud Firestore używa Twoich Cloud Firestore Security Rules, aby określić, czy żądanie jest autoryzowane.

Praca z tokenami Google Identity OAuth 2.0

Token dostępu możesz wygenerować, używając konta usługi z biblioteką klienta interfejsu API Google lub wykonując czynności opisane w artykule Korzystanie z OAuth 2.0 w aplikacjach międzyserwerowych. Token możesz też wygenerować za pomocą gcloud narzędzia wiersza poleceń i polecenia gcloud auth application-default print-access-token.

Aby wysyłać żądania do interfejsu Cloud Firestore REST API, ten token musi mieć ten zakres:

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

Jeśli uwierzytelniasz żądania za pomocą konta usługi i tokena Google Identity OAuth 2.0, Cloud Firestore zakłada, że żądania działają w imieniu Twojej aplikacji, a nie konkretnego użytkownika. Cloud Firestore pozwala tym żądaniom ignorować reguły bezpieczeństwa. Zamiast tego Cloud Firestore używa IAM aby określić, czy żądanie jest autoryzowane.

Uprawnienia dostępu kont usług możesz kontrolować, przypisując Cloud Firestore role IAM.

Uwierzytelnianie za pomocą tokena dostępu

Po uzyskaniu tokena identyfikatora Firebase lub tokena Google Identity OAuth 2.0 token, przekaż go do punktów końcowych Cloud Firestore jako nagłówek Authorization ustawiony na Bearer {YOUR_TOKEN}.

Wysyłanie wywołań REST

Wszystkie punkty końcowe interfejsu API REST znajdują się pod adresem URL https://firestore.googleapis.com/v1/.

Aby utworzyć ścieżkę do dokumentu o identyfikatorze LA w kolekcji cities w projekcie YOUR_PROJECT_ID, użyj tej struktury.

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

Aby korzystać z tej ścieżki, połącz ją z podstawowym adresem URL interfejsu API.

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

Najlepszym sposobem na rozpoczęcie eksperymentowania z interfejsem API REST jest użycie API Explorer, który automatycznie generuje tokeny Google Identity OAuth 2.0 i umożliwia sprawdzenie interfejsu API.

Metody

Poniżej znajdziesz krótkie opisy 2 najważniejszych grup metod. Pełną listę znajdziesz w dokumentacji API REST lub w API Explorer.

v1.projects.databases.documents

Wykonuj operacje CRUD na dokumentach podobne do tych, które opisano w przewodnikach Dodawanie danych i Pobieranie danych.

v1.projects.databases.collectionGroups.indexes

Wykonuj działania na indeksach, takie jak tworzenie nowych indeksów, wyłączanie istniejącego indeksu lub wyświetlanie listy wszystkich bieżących indeksów. Przydatne do automatyzacji migracji struktury danych lub synchronizowania indeksów między projektami.

Umożliwia też pobieranie metadanych dokumentu, np. listy wszystkich pól i podkolekcji danego dokumentu.

Kody błędów

Gdy żądanie Cloud Firestore zakończy się powodzeniem, interfejs Cloud Firestore API zwraca kod stanu HTTP 200 OK i żądane dane. Gdy żądanie się nie powiedzie, interfejs Cloud Firestore API zwraca kod stanu HTTP 4xx lub 5xx oraz odpowiedź z informacjami o błędzie.

W tabeli poniżej znajdziesz zalecane działania w przypadku poszczególnych kodów błędów. Te kody dotyczą interfejsów Cloud Firestore REST i RPC API. Pakiety Cloud Firestore SDK i biblioteki klienta mogą nie zwracać tych samych kodów błędów.

Kanoniczny kod błędu Opis Zalecane działanie
ABORTED Żądanie było sprzeczne z innym żądaniem. W przypadku zatwierdzenia bez transakcji:
ponów żądanie lub zmień strukturę modelu danych, aby zmniejszyć rywalizację.

W przypadku żądań w transakcji:
ponów całą transakcję lub zmień strukturę modelu danych, aby zmniejszyć rywalizację.
ALREADY_EXISTS Żądanie próbowało utworzyć dokument, który już istnieje. Nie ponawiaj próby bez rozwiązania problemu.
DEADLINE_EXCEEDED Serwer Cloud Firestore obsługujący żądanie przekroczył limit czasu. Ponów próbę ze wzrastającym czasem do ponowienia.
FAILED_PRECONDITION Żądanie nie spełniło jednego z warunków wstępnych. Na przykład żądanie zapytania może wymagać indeksu, który nie został jeszcze zdefiniowany. Warunek wstępny, który nie został spełniony, znajdziesz w polu wiadomości w odpowiedzi na błąd. Nie ponawiaj próby bez rozwiązania problemu.
INTERNAL Serwer Cloud Firestore zwrócił błąd. Nie ponawiaj tego żądania więcej niż raz.
INVALID_ARGUMENT Parametr żądania zawiera nieprawidłową wartość. Nieprawidłową wartość znajdziesz w polu wiadomości w odpowiedzi na błąd. Nie ponawiaj próby bez rozwiązania problemu.
NOT_FOUND Żądanie próbowało zaktualizować dokument, który nie istnieje. Nie ponawiaj próby bez rozwiązania problemu.
PERMISSION_DENIED Użytkownik nie jest uprawniony do wysłania tego żądania. Nie ponawiaj próby bez rozwiązania problemu.
RESOURCE_EXHAUSTED Projekt przekroczył limit lub pojemność regionu/regionu wielokrotnego. Sprawdź, czy nie przekroczono limitu projektu. Jeśli przekroczono limit projektu, nie ponawiaj próby bez rozwiązania problemu.

W przeciwnym razie ponów próbę ze wzrastającym czasem do ponowienia.
UNAUTHENTICATED Żądanie nie zawierało prawidłowych danych uwierzytelniających. Nie ponawiaj próby bez rozwiązania problemu.
UNAVAILABLE Serwer Cloud Firestore zwrócił błąd. Ponów próbę ze wzrastającym czasem do ponowienia.