Usar a API REST do Firestore

Embora a forma mais fácil de usar o Firestore seja através de uma das bibliotecas cliente nativas, existem algumas situações em que é útil chamar a API REST diretamente.

A API REST pode ser útil para os seguintes exemplos de utilização:

  • Aceder ao Firestore a partir de um ambiente com restrições de recursos, como um dispositivo da Internet das Coisas (IdC), onde não é possível executar uma biblioteca de cliente completa.
  • Automatizar a administração da base de dados ou obter metadados detalhados da base de dados.

Se estiver a usar um idioma compatível com gRPC, considere usar a API RPC em vez da API REST.

Autenticação e autorização

Para a autenticação, a API REST do Firestore aceita um símbolo de ID da autenticação Firebase ou um símbolo Google Identity OAuth 2.0. O token que fornece afeta a autorização do seu pedido:

  • Use tokens de ID do Firebase para autenticar pedidos dos utilizadores da sua aplicação. Para estes pedidos, o Firestore usa as regras de segurança do Firestore para determinar se um pedido está autorizado.

  • Use um token OAuth 2.0 da identidade Google e uma conta de serviço para autenticar pedidos da sua aplicação, como pedidos de administração da base de dados. Para estes pedidos, o Firestore usa a gestão de identidade e de acesso (IAM) para determinar se um pedido está autorizado.

Trabalhar com tokens de ID do Firebase

Pode obter um token de ID do Firebase de duas formas:

Ao obter o token de ID do Firebase de um utilizador, pode fazer pedidos em nome do utilizador.

Para pedidos autenticados com um token de ID do Firebase e para pedidos não autenticados, o Firestore usa as suas regras de segurança do Firestore para determinar se um pedido está autorizado.

Trabalhar com tokens do Google Identity OAuth 2.0

Pode gerar uma chave de acesso através de uma conta de serviço com uma biblioteca cliente de APIs Google ou seguindo os passos descritos no artigo Usar o OAuth 2.0 para aplicações de servidor para servidor. Também pode gerar um token com a ferramenta de linha de comandos gcloud e o comando gcloud auth application-default print-access-token.

Este token tem de ter o seguinte âmbito para enviar pedidos para a API REST do Firestore:

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

Se autenticar os seus pedidos com uma conta de serviço e um token OAuth 2.0 da Google Identity, o Firestore assume que os seus pedidos atuam em nome da sua aplicação em vez de um utilizador individual. O Firestore permite que estes pedidos ignorem as suas regras de segurança. Em alternativa, o Firestore usa o IAM para determinar se um pedido está autorizado.

Pode controlar as autorizações de acesso das contas de serviço atribuindo funções de IAM do Firestore.

Autenticação com um token de acesso

Depois de obter um token de ID do Firebase ou um token OAuth 2.0 da Google Identity, transmita-o aos pontos finais do Firestore como um Authorizationcabeçalho definido como Bearer {YOUR_TOKEN}.

Fazer chamadas REST

Todos os pontos finais da API REST existem no URL de base https://firestore.googleapis.com/v1/.

Para criar um caminho para um documento com o ID LA na coleção cities no projeto YOUR_PROJECT_ID, usaria a seguinte estrutura.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Para interagir com este caminho, combine-o com o URL da API de base.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

A melhor forma de começar a experimentar a API REST é usar o API Explorer, que gera automaticamente tokens OAuth 2.0 da Google Identity e permite examinar a API.

Métodos

Seguem-se breves descrições dos dois grupos de métodos mais importantes. Para ver uma lista completa, consulte a referência da API REST ou use o Explorador de APIs.

v1.projects.databases.documents

Realizar operações CRUD em documentos, semelhantes às descritas nos guias de adicionar dados ou obter dados.

v1.projects.databases.collectionGroups.indexes

Realizar ações em índices, como criar novos índices, desativar um índice existente ou listar todos os índices atuais. Útil para automatizar migrações de estrutura de dados ou sincronizar índices entre projetos.

Também permite a obtenção de metadados de documentos, como a lista de todos os campos e subcoleções de um determinado documento.

Códigos de erro

Quando um pedido do Firestore é bem-sucedido, a API Firestore devolve um código de estado HTTP 200 OK e os dados pedidos. Quando um pedido falha, a API Firestore devolve um código de estado HTTP 4xx ou 5xx e uma resposta com informações sobre o erro.

A tabela seguinte lista as ações recomendadas para cada código de erro. Estes códigos aplicam-se às APIs REST e RPC do Firestore. Os SDKs e as bibliotecas cliente do Firestore podem não devolver estes mesmos códigos de erro.

Código de erro canónico Descrição Ação recomendada
ABORTED O pedido entrou em conflito com outro pedido. Para uma confirmação não transacional:
tente novamente o pedido ou reestruture o modelo de dados para reduzir a contenção.

Para pedidos numa transação:
tente novamente a transação completa ou reestruture o modelo de dados para reduzir a contenção.
ALREADY_EXISTS O pedido tentou criar um documento que já existe. Não tente novamente sem corrigir o problema.
DEADLINE_EXCEEDED O servidor do Firestore que processa o pedido excedeu um prazo. Tente novamente com retirada exponencial.
FAILED_PRECONDITION O pedido não cumpriu uma das respetivas pré-condições. Por exemplo, um pedido 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 corrigir o problema.
INTERNAL O servidor do Firestore devolveu um erro. Não volte a tentar este pedido mais do que uma vez.
INVALID_ARGUMENT Um parâmetro de pedido inclui um valor inválido. Consulte o campo de mensagem na resposta de erro para ver o valor inválido. Não tente novamente sem corrigir o problema.
NOT_FOUND O pedido tentou atualizar um documento que não existe. Não tente novamente sem corrigir o problema.
PERMISSION_DENIED O utilizador não tem autorização para fazer este pedido. Não tente novamente sem corrigir o problema.
RESOURCE_EXHAUSTED O projeto excedeu a quota ou a capacidade da região/multirregião. Confirme que não excedeu a quota do seu projeto. Se excedeu uma quota de projeto, não tente novamente sem corrigir o problema.

Caso contrário, tente novamente com um recuo exponencial.
UNAUTHENTICATED O pedido não incluiu credenciais de autenticação válidas. Não tente novamente sem corrigir o problema.
UNAVAILABLE O servidor do Firestore devolveu um erro. Tente novamente com retirada exponencial.