Używanie interfejsu Cloud Firestore API typu REST

Najprostszym sposobem korzystania z Cloud Firestore jest użycie 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:

  • 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 tożsamości uwierzytelniania Firebase lub Token tożsamości Google OAuth 2.0. podany przez Ciebie 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ły zabezpieczeń Cloud Firestore pozwalające określić, 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ń Cloud Firestore używa Identity and Access Management (IAM), aby określić, czy żądanie jest autoryzowane.

Praca z tokenami identyfikatorów Firebase

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

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

W przypadku żądań uwierzytelnionych za pomocą tokena tożsamości Firebase i nieuwierzytelnionych żądań, Cloud Firestore używa Reguły zabezpieczeń Cloud Firestore określają, czy żądanie jest .

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. Ty token można też wygenerować za pomocą narzędzia wiersza poleceń gcloud oraz polecenie 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 zezwala na dostęp tych żądań ignorowania reguł zabezpieczeń. Zamiast tego usługa Cloud Firestore używa uprawnień do określania, czy żądanie jest autoryzowane.

Uprawnienia dostępu kont usługi możesz kontrolować przez przypisywanie Role uprawnień Cloud Firestore

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 obiekt Authorization nagłówek 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ń na indeksach, takich jak tworzenie nowych indeksów lub wyłączanie istniejących lub wyświetlić wszystkie bieżące indeksy. 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 do Cloud Firestore zostanie zrealizowane, Interfejs Cloud Firestore API zwraca kod stanu HTTP 200 OK oraz żądane dane. Jeśli żądanie nie zostanie zrealizowane, interfejs Cloud Firestore API 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 typu 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 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.