Cloud Firestore jest najprostszym sposobem korzystania z jednej z natywnych bibliotek klienta, ale są sytuacje, w których bezpośrednie wywołanie interfejsu API REST może być przydatne.
Interfejs API REST może być przydatny w tych przypadkach:
- Dostęp do Cloud Firestore można uzyskać w środowisku z ograniczonymi zasobami, takim jak urządzenie korzystające z internetu rzeczy (IoT), w którym nie można uruchomić pełnej biblioteki klienta.
- Zautomatyzowanie 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, a nie interfejsu API REST.
Uwierzytelnianie i autoryzacja
Do uwierzytelniania interfejs API typu REST Cloud Firestore akceptuje token identyfikatora uwierzytelniania Firebase lub token Google Identity OAuth 2.0. Podany token wpływa na autoryzację żądania:
Tokenów identyfikatorów Firebase możesz używać do uwierzytelniania żądań od użytkowników aplikacji. W przypadku tych żądań Cloud Firestore używa reguł zabezpieczeń Cloud Firestore, aby określić, czy dane żądanie jest autoryzowane.
Użyj tokena OAuth 2.0 tożsamości Google i konta usługi do uwierzytelniania żądań ze swojej aplikacji, takich jak żądania związane z administrowaniem bazą danych. W przypadku tych żądań Cloud Firestore używa Identity and Access Management (IAM) do określenia, czy dane żądanie jest autoryzowane.
Praca z tokenami identyfikatorów Firebase
Token identyfikatora Firebase możesz uzyskać na 2 sposoby:
- Wygeneruj token identyfikatora Firebase za pomocą interfejsu API typu REST uwierzytelniania Firebase.
- Pobierz token identyfikatora Firebase użytkownika z pakietu SDK uwierzytelniania Firebase.
Pobierając token identyfikatora Firebase użytkownika, możesz wysyłać żądania w jego imieniu.
W przypadku żądań uwierzytelnionych przy użyciu tokena identyfikatora Firebase i w przypadku żądań nieuwierzytelnionych Cloud Firestore używa reguł zabezpieczeń Cloud Firestore, aby określić, czy żądanie jest autoryzowane.
Praca z tokenami OAuth 2.0 Tożsamości Google
Token dostępu możesz wygenerować za pomocą konta usługi z biblioteką klienta interfejsu API Google lub wykonując czynności opisane w artykule Używanie OAuth 2.0 w aplikacjach między serwerami. Token możesz też wygenerować za pomocą narzędzia wiersza poleceń gcloud
i polecenia gcloud auth application-default print-access-token
.
Aby można było wysyłać żądania do interfejsu Cloud Firestore API typu REST, token musi mieć następujący zakres:
https://www.googleapis.com/auth/datastore
Jeśli uwierzytelniasz żądania za pomocą konta usługi i tokena OAuth 2.0 tożsamości Google, Cloud Firestore zakłada, że żądania działają w imieniu aplikacji, a nie poszczególnych użytkowników. Cloud Firestore zezwala na ignorowanie reguł zabezpieczeń przez te żądania. Zamiast tego Cloud Firestore używa uprawnień do określania, czy żądanie jest autoryzowane.
Uprawnieniami dostępu do kont usługi możesz kontrolować, przypisując role uprawnień Cloud Firestore.
Uwierzytelnianie przy użyciu tokena dostępu
Po uzyskaniu tokena identyfikatora Firebase lub tokena OAuth 2.0 Google Identity przekaż go do punktów końcowych Cloud Firestore jako nagłówek Authorization
z wartością Bearer {YOUR_TOKEN}
.
Wykonywanie wywołań 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 kolekcji cities
w projekcie YOUR_PROJECT_ID
, użyj poniższej 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 eksperymentów z interfejsem API REST jest użycie narzędzia API Explorer, które automatycznie generuje tokeny OAuth 2.0 tożsamości Google i umożliwia poznanie interfejsu API.
Metody
Poniżej znajduje się krótkie opisy 2 najważniejszych grup metod. Pełną listę znajdziesz w dokumentacji interfejsu API REST lub w narzędziu API Explorer.
v1.projects.databases.documents
Wykonuj na dokumentach operacje CRUD podobne do opisanych w przewodnikach dotyczących dodawania danych i pobierania danych.
v1.projects.databases.collectionGroups.indexes
Wykonywanie działań dotyczących indeksów, takich jak tworzenie nowych indeksów, wyłączanie istniejącego indeksu lub wyświetlanie listy wszystkich bieżących indeksów. Przydaje się do automatyzacji migracji struktury danych lub synchronizowania indeksów między projektami.
Umożliwia też pobieranie metadanych dokumentów, takich jak lista wszystkich pól i kolekcji podrzędnych danego dokumentu.
Kody błędów
Jeśli żądanie do Cloud Firestore zostanie zrealizowane, interfejs Cloud Firestore API zwróci kod stanu HTTP 200 OK
i żądane dane. Jeśli żądanie nie powiedzie się, interfejs Cloud Firestore API zwróci kod stanu HTTP 4xx
lub 5xx
oraz odpowiedź z informacjami o błędzie.
W tabeli poniżej znajdziesz zalecane działania w przypadku każdego kodu błędu. Te kody mają zastosowanie do interfejsów API typu REST i RPC w 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 spowodowało konflikt z innym żądaniem. | W przypadku zatwierdzenia nietransakcyjnego: Ponów żądanie lub zmień strukturę modelu danych, aby ograniczyć rywalizację. W przypadku żądań w transakcji: Ponów próbę całej transakcji lub zmień strukturę modelu danych, aby ograniczyć 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ł termin. | Spróbuj ponownie 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. Sprawdź pole komunikatu w odpowiedzi na błąd dotyczący warunku wstępnego, który nie został spełniony. | Nie ponawiaj próby bez rozwiązania 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ść. Sprawdź nieprawidłową wartość w polu komunikatu w odpowiedzi na błąd. | Nie ponawiaj próby bez rozwiązania problemu. |
NOT_FOUND |
W ramach żądania podjęto próbę zaktualizowania nieistniejącego dokumentu. | Nie ponawiaj próby bez rozwiązania problemu. |
PERMISSION_DENIED |
Użytkownik nie ma uprawnień do przesłania tego żądania. | Nie ponawiaj próby bez rozwiązania problemu. |
RESOURCE_EXHAUSTED |
Projekt przekroczył swój limit lub limit regionu bądź wielu regionów. | Sprawdź, czy limit projektu nie został przekroczony. Jeśli przekroczysz limit projektu, nie ponawiaj próby bez rozwiązania problemu. W przeciwnym razie spróbuj ponownie 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. | Spróbuj ponownie ze wzrastającym czasem do ponowienia. |