Używanie interfejsu Cloud Firestore API typu REST

Najprostszym sposobem korzystania z Cloud Firestore jest użycie jednej z bibliotek klienta natywnych, ale w niektórych sytuacjach przydatne może być bezpośrednie wywołanie interfejsu API REST.

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

  • korzystania z usługi Cloud Firestore w środowisku o ograniczonych zasobach, 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 zamiast interfejsu REST API.

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 token wpływa na autoryzację żądania:

  • Używaj tokenów Firebase ID do uwierzytelniania żądań wysyłanych przez 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 Google Identity OAuth 2.0 i konta usługi do uwierzytelniania żądań z aplikacji, takich jak żądania administracji bazy danych. W przypadku tych żą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 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 Google Identity OAuth 2.0

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 sekcji 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, token musi mieć ten zakres:

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

Jeśli uwierzytelniasz żądania za pomocą konta usługi i tokena OAuth 2.0 Google Identity, Cloud Firestore zakłada, że żądania są wysyłane w imieniu aplikacji, a nie konkretnego użytkownika. Cloud Firestore pozwala tym żądaniom ignorować reguły zabezpieczeń. Zamiast tego usługa Cloud Firestore używa usługi zarządzania dostępem (IAM) do określenia, czy żądanie jest autoryzowane.

Możesz kontrolować uprawnienia dostępu kont usługi, przypisując role uprawnień Cloud Firestore.

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 w postaci nagłówka 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 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 skorzystanie z API Explorer, który automatycznie generuje tokeny tożsamości Google OAuth 2.0 i pozwala na analizowanie 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 narzędzie API Explorer.

v1.projects.databases.documents

Wykonywanie operacji CRUD na dokumentach, podobnych do tych opisanych w przewodniku dodawanie danych lub pobieranie 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 wszystkich bieżących indeksów. Przydaje się do automatyzacji migracji struktury danych lub synchronizacji indeksów między projektami.

Umożliwia też pobieranie metadanych dokumentu, takich jak lista wszystkich pól i podkolekcji danego dokumentu.

Kody błędów

Gdy żądanie Cloud Firestore zakończy się powodzeniem, interfejs API Cloud Firestore zwróci kod stanu HTTP 200 OK oraz żądane dane. Gdy żądanie nie powiedzie się, 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 w przypadku każdego kodu błędu. Te kody dotyczą interfejsów API REST i RPC Cloud Firestore. Pakiety Cloud FirestoreSDK i biblioteki klienta mogą nie zwracać tych samych kodów błędów.

Kanoniczny kod błędu Opis Zalecane działanie
ABORTED Żądanie kolidowało 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 W ramach żądania nastąpiła próba utworzenia dokumentu, który już istnieje. Nie próbuj ponownie, jeśli problem nie został rozwiązany.
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 zapytanie może wymagać indeksu, który nie został jeszcze zdefiniowany. Sprawdź pole komunikatu w odpowiedzi na błąd dla 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ść. Nieprawidłową wartość znajdziesz w polu komunikatu w odpowiedzi na błąd. Nie próbuj ponownie, jeśli problem nie został rozwiązany.
NOT_FOUND Żądanie próbowało zaktualizować dokument, który nie istnieje. Nie próbuj ponownie, jeśli problem nie został rozwiązany.
PERMISSION_DENIED Użytkownik nie ma uprawnień do wykonania tego żądania. Nie próbuj ponownie, jeśli problem nie został rozwiązany.
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, 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 próbuj ponownie, jeśli problem nie został rozwiązany.
UNAVAILABLE Serwer Cloud Firestore zwrócił błąd. Ponownie spróbuj, używając wzrastającego czasu do ponowienia.