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 jest bezpośrednie wywołanie interfejsu API REST.

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

  • Uzyskiwanie dostępu do Cloud Firestore ze środowiska o ograniczonych zasobach, takiego jak urządzenie 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ługiwanego przez gRPC, rozważ użycie interfejsu RPC API zamiast interfejsu REST API.

Uwierzytelnianie i autoryzacja

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

  • Używaj tokenów identyfikacyjnych 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żyj tokena OAuth 2.0 Google Identity i konta usługi do uwierzytelniania żądań z aplikacji, takich jak żądania dotyczące 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 i żądań nieuwierzytelnionych Cloud Firestore używa Cloud Firestore Security Rules, aby określić, czy żądanie jest autoryzowane.

Praca z tokenami OAuth 2.0 Google Identity

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

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

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

Jeśli uwierzytelniasz żądania za pomocą konta usługi i tokena OAuth 2.0 Google Identity, Cloud Firestore zakłada, że żądania działają w imieniu aplikacji, a nie pojedynczego użytkownika. Cloud Firestore umożliwia tym żądaniom ignorowanie reguł zabezpieczeń. Zamiast tego Cloud Firestore używa uprawnień, aby określić, czy żądanie jest autoryzowane.

Uprawnieniami dostępu kont usługi możesz zarządzać, przypisując role uprawnień Cloud Firestore.

Uwierzytelnianie za pomocą tokena dostępu

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

Wykonywanie wywołań REST

Wszystkie punkty końcowe API typu REST znajdują się pod podstawowym 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 REST API jest użycie narzędzia APIs Explorer, które automatycznie generuje tokeny OAuth 2.0 Google Identity 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 typu REST lub w narzędziu APIs Explorer.

v1.projects.databases.documents

wykonywać operacje CRUD na dokumentach, podobnie jak opisano w przewodnikach dodawanie danych i pobieranie danych;

v1.projects.databases.collectionGroups.indexes

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

Umożliwia też pobieranie metadanych dokumentu, takich jak lista wszystkich pól i podkolekcji danego dokumentu.

Kody błędów

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

W tabeli poniżej znajdziesz zalecane działania dla każdego kodu błędu. Te kody dotyczą interfejsów API REST i RPC Cloud Firestore. Pakiety SDK i biblioteki klienta Cloud Firestore 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 nietransakcyjnego:
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 próbuj ponownie, dopóki nie rozwiążesz problemu.
DEADLINE_EXCEEDED Serwer Cloud Firestore obsługujący żądanie przekroczył termin. Ponów próbę, używając wzrastającego czasu 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. Sprawdź pole wiadomości w odpowiedzi o błędzie, aby dowiedzieć się, który warunek wstępny nie został spełniony. Nie próbuj ponownie, dopóki nie rozwiążesz problemu.
INTERNAL Serwer Cloud Firestore zwrócił błąd. Nie ponawiaj tej prośby więcej niż raz.
INVALID_ARGUMENT Parametr żądania zawiera nieprawidłową wartość. Nieprawidłową wartość znajdziesz w polu wiadomości w odpowiedzi o błędzie. Nie próbuj ponownie, dopóki nie rozwiążesz problemu.
NOT_FOUND Żądanie próbowało zaktualizować dokument, który nie istnieje. Nie próbuj ponownie, dopóki nie rozwiążesz problemu.
PERMISSION_DENIED Użytkownik nie ma uprawnień do wykonania tego żądania. Nie próbuj ponownie, dopóki nie rozwiążesz problemu.
RESOURCE_EXHAUSTED Projekt przekroczył limit lub pojemność regionu bądź wielu regionów. Sprawdź, czy nie został przekroczony limit projektu. Jeśli przekroczysz limit projektu, nie próbuj ponownie, dopóki nie rozwiążesz problemu.

W przeciwnym razie spróbuj ponownie ze wzrastającym czasem do ponowienia.
UNAUTHENTICATED Żądanie nie zawierało prawidłowych danych uwierzytelniających. Nie próbuj ponownie, dopóki nie rozwiążesz problemu.
UNAVAILABLE Serwer Cloud Firestore zwrócił błąd. Ponów próbę, używając wzrastającego czasu do ponowienia.