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ływanie interfejsu REST API.

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

  • Dostęp do Cloud Firestore w środowisku o ograniczonych zasobach, np. na urządzeniu internetu rzeczy (IoT), w którym nie można uruchomić pełnej biblioteki klienta.
  • automatyzowanie administrowania bazą danych lub pobieranie szczegółowych metadanych bazy danych;

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

Uwierzytelnianie i autoryzacja

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

  • Używaj tokenów identyfikatora Firebase do uwierzytelniania żądań użytkowników aplikacji. W przypadku tych żądań Cloud Firestore używa Cloud Firestore Security Rules, aby określić, czy żądanie jest autoryzowane.

  • Używaj tokena OAuth 2.0 Google Identity i konta usługi do uwierzytelniania żądań z aplikacji, np. żądań dotyczących administracji bazą danych. W przypadku tych żądań usługa Cloud Firestore korzysta z Identity and Access Management (IAM), aby określić, czy żądanie jest autoryzowane.

Praca z tokenami identyfikatorów Firebase

Token identyfikacyjny 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 nieuwierzytelnionych żądań Cloud Firestore używa Twojego 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 interfejsu API Google lub wykonując czynności opisane w artykule Używanie protokołu OAuth 2.0 w aplikacjach międzyserwerowych. 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 Cloud Firestore REST API, ten token musi mieć ten zakres:

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

Jeśli uwierzytelniasz żądania za pomocą konta usługi i tokena Google Identity OAuth 2.0, Cloud Firestore zakłada, że żądania są wykonywane w imieniu aplikacji, a nie użytkownika. Cloud Firestore zezwala na ignorowanie reguł zabezpieczeń w przypadku tych żądań. Zamiast tego Cloud Firestore używa IAM, aby określić, czy żądanie jest autoryzowane.

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

Uwierzytelnianie za pomocą 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 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 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 API Explorer, który 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 interfejsu API REST lub w API Explorerze.

v1.projects.databases.documents

wykonywać operacje CRUD na dokumentach podobne do tych opisanych w przewodnikach dodawanie danych i pobieranie danych.

v1.projects.databases.collectionGroups.indexes

Wykonywanie działań na indeksach, takich jak tworzenie nowych indeksów, wyłączanie istniejącego indeksu lub wyświetlanie listy wszystkich bieżących indeksów. Przydatne do automatyzacji migracji struktury danych lub synchronizowania indeksów między projektami.

Umożliwia też pobieranie metadanych dokumentu, takich jak lista wszystkich pól i podzbiorów w danym dokumencie.

Kody błędów

Gdy żądanie Cloud Firestore zakończy się powodzeniem, interfejs Cloud Firestore API zwraca kod stanu HTTP 200 OK i żądane dane. Gdy żą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 Cloud Firestore REST i RPC. Cloud FirestorePakiety SDK i biblioteki klienta 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 W ramach żądania podjęto próbę utworzenia dokumentu, który już istnieje. Nie próbuj ponownie bez rozwiązania problemu.
DEADLINE_EXCEEDED Serwer Cloud Firestore obsługujący żądanie przekroczył termin. Ponów próbę 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. W polu komunikatu w odpowiedzi na błąd znajdziesz warunek wstępny, który nie został spełniony. Nie próbuj ponownie bez rozwiązania problemu.
INTERNAL Cloud Firestore serwer 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 komunikatu w odpowiedzi o błędzie. Nie próbuj ponownie bez rozwiązania problemu.
NOT_FOUND Żądanie próbowało zaktualizować dokument, który nie istnieje. Nie próbuj ponownie bez rozwiązania problemu.
PERMISSION_DENIED Użytkownik nie ma uprawnień do wykonania tego żądania. Nie próbuj ponownie bez rozwiązania problemu.
RESOURCE_EXHAUSTED Projekt przekroczył limit lub pojemność regionu/wielu regionów. Sprawdź, czy nie został przekroczony limit projektu. Jeśli przekroczysz limit projektu, nie próbuj ponownie bez rozwiązania problemu.

W przeciwnym razie spróbuj ponownie ze wzrastającym czasem ponowienia.
UNAUTHENTICATED Żądanie nie zawierało prawidłowych danych uwierzytelniających. Nie próbuj ponownie bez rozwiązania problemu.
UNAVAILABLE Cloud Firestore serwer zwrócił błąd. Ponów próbę ze wzrastającym czasem do ponowienia.