Embora a maneira mais fácil de usar o Cloud Firestore seja usar uma das bibliotecas de cliente nativas, há algumas situações em que é útil chamar a API REST diretamente.
A API REST pode ser útil para os seguintes casos de uso:
- Acessar o Cloud Firestore em um ambiente com recursos limitados, como um dispositivo de Internet das Coisas (IoT), onde não é possível executar uma biblioteca cliente completa.
- Automatizando a administração do banco de dados ou recuperando metadados detalhados do banco de dados.
Se você estiver usando uma linguagem compatível com gRPC , considere usar a API RPC em vez da API REST.
Autenticação e autorização
Para autenticação, a API REST do Cloud Firestore aceita um token de ID do Firebase Authentication ou um token do Google Identity OAuth 2.0 . O token fornecido afeta a autorização da sua solicitação:
Use tokens de ID do Firebase para autenticar solicitações dos usuários do seu aplicativo. Para essas solicitações, o Cloud Firestore usa as regras de segurança do Cloud Firestore para determinar se uma solicitação é autorizada.
Use um token Google Identity OAuth 2.0 e uma conta de serviço para autenticar solicitações do seu aplicativo, como solicitações de administração de banco de dados. Para essas solicitações, o Cloud Firestore usa o gerenciamento de identidade e acesso (IAM) para determinar se uma solicitação está autorizada.
Trabalhando com tokens de ID do Firebase
Você pode obter um token de ID do Firebase de duas maneiras:
- Gere um token de ID do Firebase usando a API REST do Firebase Authentication .
- Recuperar o token de ID do Firebase de um usuário de um SDK do Firebase Authentication .
Ao recuperar o token de ID do Firebase de um usuário, você pode fazer solicitações em nome do usuário.
Para solicitações autenticadas com um token de ID do Firebase e para solicitações não autenticadas, o Cloud Firestore usa as regras de segurança do Cloud Firestore para determinar se uma solicitação está autorizada.
Trabalhando com tokens do Google Identity OAuth 2.0
Você pode gerar um token de acesso usando uma conta de serviço com uma biblioteca cliente da API do Google ou seguindo as etapas em Usando o OAuth 2.0 para aplicativos de servidor para servidor . Você também pode gerar um token com a ferramenta de linha de comando gcloud e o comando gcloud auth application-default print-access-token .
Esse token deve ter o seguinte escopo para enviar solicitações à API REST do Cloud Firestore:
-
https://www.googleapis.com/auth/datastore
Se você autenticar suas solicitações com uma conta de serviço e um token do Google Identity OAuth 2.0, o Cloud Firestore presumirá que suas solicitações agem em nome do seu aplicativo, e não de um usuário individual. O Cloud Firestore permite que essas solicitações ignorem suas regras de segurança. Em vez disso, o Cloud Firestore usa o IAM para determinar se uma solicitação está autorizada.
Você pode controlar as permissões de acesso das contas de serviço atribuindo funções IAM do Cloud Firestore .
Autenticando com um token de acesso
Depois de obter um token de ID do Firebase ou um token do Google Identity OAuth 2.0, transmita-o aos endpoints do Cloud Firestore como um cabeçalho Authorization definido como Bearer {YOUR_TOKEN} .
Fazendo chamadas REST
Todos os endpoints da API REST existem no URL base https://firestore.googleapis.com/v1/ .
Para criar um caminho para um documento com o ID LA nas cities de coleta no projeto YOUR_PROJECT_ID você usaria a seguinte estrutura.
/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA
Para interagir com esse caminho, combine-o com o URL base da API.
https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA
A melhor maneira de começar a experimentar a API REST é usar o API Explorer , que gera automaticamente tokens do Google Identity OAuth 2.0 e permite examinar a API.
Métodos
Abaixo estão breves descrições dos dois grupos de métodos mais importantes. Para obter uma lista completa, consulte a referência da API REST ou use o API Explorer .
v1.projects.databases.documents
Execute operações CRUD em documentos, semelhantes às descritas nos guias de adição ou obtenção de dados .
v1.projects.databases.collectionGroups.indexes
Execute ações em índices, como criar novos índices, desabilitar um índice existente ou listar todos os índices atuais. Útil para automatizar migrações de estruturas de dados ou sincronizar índices entre projetos.
Também permite a recuperação de metadados de documentos, como a lista de todos os campos e subcoleções de um determinado documento.
Códigos de erro
Quando uma solicitação do Cloud Firestore é bem-sucedida, a API Cloud Firestore retorna um código de status HTTP 200 OK e os dados solicitados. Quando uma solicitação falha, a API Cloud Firestore retorna um código de status HTTP 4xx ou 5xx e uma resposta com informações sobre o erro.
A tabela a seguir lista as ações recomendadas para cada código de erro. Esses códigos se aplicam às APIs REST e RPC do Cloud Firestore. Os SDKs e bibliotecas cliente do Cloud Firestore podem não retornar esses mesmos códigos de erro.
| Código de erro canônico | Descrição | Ação recomendada |
|---|---|---|
ABORTED | A solicitação entrou em conflito com outra solicitação. | Para um commit não transacional: Tente novamente a solicitação ou reestruture seu modelo de dados para reduzir a contenção. Para solicitações em uma transação: Tente novamente toda a transação ou reestruture seu modelo de dados para reduzir a contenção. |
ALREADY_EXISTS | A solicitação tentou criar um documento que já existe. | Não tente novamente sem resolver o problema. |
DEADLINE_EXCEEDED | O servidor Cloud Firestore que atendeu a solicitação excedeu o prazo. | Tente novamente usando espera exponencial. |
FAILED_PRECONDITION | O pedido não cumpriu uma das suas condições prévias. Por exemplo, uma solicitação de consulta pode exigir um índice ainda não definido. Consulte o campo de mensagem na resposta de erro para a pré-condição que falhou. | Não tente novamente sem resolver o problema. |
INTERNAL | O servidor Cloud Firestore retornou um erro. | Não repita esta solicitação mais de uma vez. |
INVALID_ARGUMENT | Um parâmetro de solicitação inclui um valor inválido. Consulte o campo de mensagem na resposta de erro para obter o valor inválido. | Não tente novamente sem resolver o problema. |
NOT_FOUND | A solicitação tentou atualizar um documento que não existe. | Não tente novamente sem resolver o problema. |
PERMISSION_DENIED | O usuário não está autorizado a fazer esta solicitação. | Não tente novamente sem resolver o problema. |
RESOURCE_EXHAUSTED | O projeto excedeu a sua quota ou a capacidade regional/multirregional. | Verifique se você não excedeu a cota do projeto . Se você excedeu a cota do projeto, não tente novamente sem corrigir o problema. Caso contrário, tente novamente com espera exponencial. |
UNAUTHENTICATED | A solicitação não incluiu credenciais de autenticação válidas. | Não tente novamente sem resolver o problema. |
UNAVAILABLE | O servidor Cloud Firestore retornou um erro. | Tente novamente usando espera exponencial. |