Najłatwiejszym sposobem korzystania z Cloud Firestore jest użycie jednej z natywnych bibliotek klienta, są sytuacje, w których przydaje się bezpośrednio wywoływać interfejs API REST.
Interfejs API REST może być przydatny w tych przypadkach:
- uzyskując dostęp do Cloud Firestore ze środowiska z ograniczonymi zasobami; na przykład na urządzeniu z internetem rzeczy (IoT), na którym działa kompletny klient .
- Zautomatyzowanie administrowania bazą danych lub pobieranie szczegółowych metadanych bazy danych.
Jeśli używasz języka obsługiwanego przez gRPC, rozważ użycie Interfejs RPC API zamiast interfejsu API REST.
Uwierzytelnianie i autoryzacja
Do uwierzytelniania interfejs API REST Cloud Firestore akceptuje token identyfikatora Firebase Authentication lub token tożsamości Google OAuth 2.0. podany przez Ciebie token, wpływa na autoryzację żądania:
Używaj tokenów identyfikatorów Firebase do uwierzytelniania żądań użytkowników aplikacji. W przypadku tych żądań Cloud Firestore używa Cloud Firestore Security Rules, aby sprawdzić, czy żądanie jest autoryzowany.
Użyj tokena OAuth 2.0 tożsamości Google konta usługi do uwierzytelniania żądań pochodzących z takich jak żądania administrowania bazami danych. W przypadku takich żądań Zastosowania: Cloud Firestore Identity and Access Management (IAM), aby określić, czy żądanie jest autoryzowane.
Praca z tokenami identyfikatora Firebase
Token Firebase ID możesz uzyskać na 2 sposoby:
- Wygeneruj token identyfikatora Firebase za pomocą Firebase Authentication API typu REST.
- Pobierz token identyfikatora Firebase użytkownika z Pakiet SDK Firebase Authentication.
Pobierając token identyfikatora Firebase użytkownika, możesz wysyłać żądania w jego imieniu.
W przypadku żądań uwierzytelnionych za pomocą tokena Firebase ID oraz żądań niezaufanego Cloud Firestore używa Twojego Cloud Firestore Security Rules, 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
Biblioteka klienta interfejsów API Google
lub wykonując czynności opisane na stronie
Używanie protokołu OAuth 2.0 w aplikacjach między serwerami. Możesz też wygenerować token za pomocą narzędzia wiersza poleceń gcloud
i polecenia gcloud auth application-default print-access-token
.
Ten token musi mieć następujący zakres, aby wysyłać żądania do Interfejs API typu REST Cloud Firestore:
https://www.googleapis.com/auth/datastore
Jeśli uwierzytelniasz żądania za pomocą konta usługi i tożsamości Google OAuth 2.0, Cloud Firestore zakłada, że Twoje żądania działają w imieniu Twojej aplikacji, a nie poszczególnych użytkowników. Cloud Firestore zezwoleń tych żądań ignorowania reguł zabezpieczeń. Zamiast tego: Cloud Firestore używa uprawnień do określania, czy żądanie jest autoryzowane.
Uprawnienia dostępu kont usługi możesz kontrolować przez przypisywanie Cloud Firestore ról uprawnień.
Uwierzytelnianie przy użyciu tokena dostępu
Gdy uzyskasz token identyfikatora Firebase lub protokół OAuth 2.0 Google Identity
token, przekaż go do punktów końcowych Cloud Firestore jako Authorization
nagłówek został ustawiony na 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 ramach projektu YOUR_PROJECT_ID
użyjesz 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 eksperymentów z interfejsem API REST jest użycie API Explorer, który automatycznie generuje tożsamość Google; OAuth 2.0 i umożliwia poznanie interfejsu API.
Metody
Poniżej znajduje się krótkie opisy 2 najważniejszych grup metod. Pełną listę zapoznaj się z dokumentacją interfejsu API REST lub skorzystaj z narzędzia API Explorer.
v1.projects.databases.documents
Wykonuj operacje CRUD na dokumentach podobne do opisanych w dodaj dane lub pobierz dane.
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 wszystkich bieżących indeksów. Przydatne do automatyzacji struktury danych migracji ani synchronizowania indeksów między projektami.
Umożliwia też pobieranie metadanych dokumentów, takich jak lista pól i podkolekcji związanych z danym dokumentem.
Kody błędów
Jeśli żądanie Cloud Firestore zostanie zrealizowane,
Interfejs API Cloud Firestore zwraca kod stanu HTTP 200 OK
, a funkcja
żądane dane. Jeśli żądanie nie zostanie zrealizowane, interfejs API Cloud Firestore zwróci błąd
Kod stanu HTTP 4xx
lub 5xx
i odpowiedź z informacjami o tym
błąd.
W tabeli poniżej znajdziesz zalecane działania w przypadku każdego kodu błędu. Obowiązują te kody do interfejsów API REST i RPC Cloud Firestore. Cloud Firestore Pakiety SDK i biblioteki klienta 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 zatwierdzania nietransakcyjnego: ponów wysłanie żądania lub zmodyfikuj strukturę modelu danych, aby zmniejszyć rywalizację. W przypadku żądań w ramach transakcji: ponów całą transakcję lub zmodyfikuj 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ł 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 próbuj ponownie, jeśli problem nie został rozwiązany. |
INTERNAL |
Serwer Cloud Firestore zwrócił błąd. | Nie próbuj ponownie wysyłać 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 próbuj ponownie, jeśli problem nie został rozwiązany. |
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 próbuj ponownie, dopóki nie rozwiążesz problemu. W przeciwnym razie spróbuj ponownie, stosując wykładniczy czas 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. |