Używanie interfejsu Cloud Firestore API typu REST

Najprostszym 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 API REST Cloud Firestore akceptuje token identyfikatora Firebase Authentication lub token Google Identity OAuth 2.0. Podany token wpływa na autoryzację żądania:

  • Używaj tokenów identyfikacyjnych Firebase do uwierzytelniania żądań użytkowników aplikacji. W przypadku tych żądań usługa 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 administrowania 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 identyfikacyjnymi Firebase

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

Pobierając identyfikator 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 API REST Cloud Firestore, ten 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ą wykonywane w imieniu aplikacji, a nie użytkownika. Cloud Firestore umożliwia tym żądaniom ignorowanie reguł zabezpieczeń. Zamiast tego Cloud Firestore używa IAM do określania, 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 Google Identity OAuth 2.0 i umożliwia sprawdzenie interfejsu API.

Metody

Poniżej znajdziesz krótkie opisy 2 najważniejszych grup metod. Pełną listę znajdziesz w materiałach referencyjnych interfejsu API REST lub w API Explorer.

v1.projects.databases.documents

Wykonuj operacje CRUD na dokumentach podobne do tych, które opisano w przewodnikach dodawanie danych i pobieranie danych.

v1.projects.databases.collectionGroups.indexes

wykonywać działania na indeksach, takie 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 danego dokumentu.

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 Cloud Firestore API 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 typu REST i RPC Cloud Firestore. 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 Prośba była sprzeczna z inną prośbą. W przypadku zatwierdzenia bez transakcji:
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 Serwer Cloud Firestore zwrócił błąd. Nie próbuj ponownie więcej niż raz.
INVALID_ARGUMENT Parametr żądania zawiera nieprawidłową wartość. Nieprawidłowa wartość znajduje się w polu wiadomości 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 do ponowienia.
UNAUTHENTICATED Żądanie nie zawierało prawidłowych danych uwierzytelniających. Nie próbuj ponownie bez rozwiązania problemu.
UNAVAILABLE Serwer Cloud Firestore zwrócił błąd. Ponów próbę ze wzrastającym czasem do ponowienia.