Użyj interfejsu Cloud Firestore REST API

Chociaż najłatwiejszym sposobem korzystania z Cloud Firestore jest użycie jednej z natywnych bibliotek klienta, w niektórych sytuacjach przydatne jest bezpośrednie wywołanie interfejsu API REST.

Interfejs API REST może być pomocny w następujących przypadkach użycia:

Dostęp do Cloud Firestore ze środowiska o ograniczonych zasobach, takiego jak urządzenie Internetu rzeczy (IoT), gdzie uruchomienie pełnej biblioteki klienckiej nie jest możliwe.
Automatyzacja administrowania bazami danych lub pobieranie szczegółowych metadanych z bazy danych.

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

Uwierzytelnianie i autoryzacja

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

Użyj tokenów Firebase ID do uwierzytelniania żądań od użytkowników aplikacji. W przypadku tych żądań Cloud Firestore korzysta z reguł bezpieczeństwa Cloud Firestore w celu ustalenia, czy żądanie jest autoryzowane.
Użyj tokena Google Identity OAuth 2.0 i konta usługi , aby uwierzytelniać żądania z aplikacji, takie jak żądania administrowania bazą danych. W przypadku tych żądań Cloud Firestore korzysta z zarządzania tożsamością i dostępem (IAM) , aby określić, czy żądanie jest autoryzowane.

Praca z tokenami identyfikacyjnymi Firebase

Możesz zdobyć token Firebase ID na dwa sposoby:

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

W przypadku żądań uwierzytelnionych za pomocą tokena identyfikatora Firebase i żądań nieuwierzytelnionych Cloud Firestore korzysta z reguł bezpieczeństwa Cloud Firestore w celu ustalenia, czy żądanie jest autoryzowane.

Praca z tokenami Google Identity OAuth 2.0

Token dostępu możesz wygenerować, korzystając z konta usługi w bibliotece klienta API Google lub postępując zgodnie z instrukcjami w temacie Korzystanie z protokołu OAuth 2.0 w aplikacjach serwer-serwer . Możesz także wygenerować token za pomocą narzędzia wiersza poleceń gcloud i polecenia gcloud auth application-default print-access-token .

Token ten musi mieć następujący zakres, aby wysyłać żądania do interfejsu API REST Cloud Firestore:

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

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

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

Uwierzytelnianie za pomocą tokena dostępu

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

Wykonywanie połączeń REST

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

Aby utworzyć ścieżkę do dokumentu o identyfikatorze LA w cities kolekcji w ramach projektu YOUR_PROJECT_ID , należy zastosować następującą strukturę.

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

Aby wejść w interakcję z tą ścieżką, 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 eksperymentów z REST API jest skorzystanie z Eksploratora API , który automatycznie generuje tokeny Google Identity OAuth 2.0 i umożliwia sprawdzenie API.

Metody

Poniżej znajdują się krótkie opisy dwóch najważniejszych grup metod. Pełną listę można znaleźć w dokumentacji interfejsu API REST lub skorzystać z Eksploratora API .

`v1.projects.databases.documents`

Wykonuj operacje CRUD na dokumentach, podobne do tych opisanych w przewodnikach dodawania lub pobierania 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 wszystkich bieżących indeksów. Przydatne do automatyzacji migracji struktur danych lub synchronizacji indeksów pomiędzy projektami.

Umożliwia także pobranie metadanych dokumentu, takich jak lista wszystkich pól i podkolekcji dla danego dokumentu.

Kody błędów

Gdy żądanie Cloud Firestore powiedzie się, interfejs API Cloud Firestore zwraca kod stanu HTTP 200 OK i żądane dane. Gdy żądanie nie powiedzie się, interfejs API Cloud Firestore zwraca kod stanu HTTP 4xx lub 5xx oraz odpowiedź zawierającą informację o błędzie.

W poniższej tabeli wymieniono zalecane działania dla każdego kodu błędu. Kody te dotyczą interfejsów API REST i RPC Cloud Firestore. Zestawy SDK Cloud Firestore i biblioteki klienckie mogą nie zwracać tych samych kodów błędów.

Kanoniczny kod błędu	Opis	Rekomendowane działanie
`ABORTED`	Żądanie kolidowało 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`	W żądaniu podjęto próbę utworzenia dokumentu, który już istnieje.	Nie próbuj ponownie bez naprawienia problemu.
`DEADLINE_EXCEEDED`	Serwer Cloud Firestore obsługujący żądanie przekroczył termin.	Spróbuj ponownie, używając wykładniczego wycofywania.
`FAILED_PRECONDITION`	Żądanie nie spełniło jednego z warunków wstępnych. Na przykład żądanie zapytania może wymagać jeszcze niezdefiniowanego indeksu. Zobacz pole komunikatu w odpowiedzi na błąd dotyczące warunku wstępnego, który się nie powiódł.	Nie próbuj ponownie bez naprawienia 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ść. Sprawdź, czy w polu komunikatu w odpowiedzi na błąd znajduje się nieprawidłowa wartość.	Nie próbuj ponownie bez naprawienia problemu.
`NOT_FOUND`	W żądaniu podjęto próbę aktualizacji dokumentu, który nie istnieje.	Nie próbuj ponownie bez naprawienia problemu.
`PERMISSION_DENIED`	Użytkownik nie jest upoważniony do złożenia tego żądania.	Nie próbuj ponownie bez naprawienia problemu.
`RESOURCE_EXHAUSTED`	Projekt przekroczył swój limit lub możliwości regionalne/wieloregionalne.	Sprawdź, czy nie przekroczyłeś limitu projektu . Jeśli przekroczyłeś limit projektu, nie próbuj ponownie bez naprawienia problemu. W przeciwnym razie spróbuj ponownie z wykładniczym wycofaniem.
`UNAUTHENTICATED`	Żądanie nie zawierało prawidłowych danych uwierzytelniających.	Nie próbuj ponownie bez naprawienia problemu.
`UNAVAILABLE`	Serwer Cloud Firestore zwrócił błąd.	Spróbuj ponownie, używając wykładniczego wycofywania.