Usar a API REST do Cloud Firestore

A maneira mais fácil de usar o Cloud Firestore é usar uma das bibliotecas de cliente nativas, mas há algumas situações em que é melhor chamar a API REST diretamente.

A API REST pode ser útil nos seguintes casos de uso:

  • Ao acessar o Cloud Firestore por um ambiente com recursos restritos, como um dispositivo de Internet das coisas (IoT, na sigla em inglês), em que não é possível executar uma biblioteca cliente completa.
  • Ao automatizar a administração ou recuperar metadados detalhados do banco de dados.

Se você estiver usando uma linguagem compatível com gRPC (em inglês), utilize a API RPC em vez da REST.

Autenticação e autorização

Para fazer a 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 código do Firebase para autenticar solicitações dos usuários do seu aplicativo. Para essas solicitações, o Cloud Firestore usa o Cloud Firestore Security Rules para determinar se uma solicitação tem autorização.

  • Use um token do Google Identity OAuth 2.0 e uma conta de serviço para autenticar solicitações do seu aplicativo, como solicitações de administração do banco de dados. Para essas solicitações, o Cloud Firestore usa o Identity and Access Management (IAM) para determinar se uma solicitação está autorizada.

Como usar tokens de ID do Firebase

Você pode receber um token de código do Firebase de duas maneiras:

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 suas Cloud Firestore Security Rules para determinar se uma solicitação está autorizada.

Como usar tokens do Google Identity OAuth 2.0

Para gerar um token de acesso, use uma conta de serviço com uma biblioteca de cliente da API do Google ou siga as etapas em Como usar o OAuth 2.0 para aplicativos de servidor para servidor (em inglês). Também é possível gerar um token com a ferramenta de linha de comando gcloud e o comando gcloud auth application-default print-access-token (em inglês).

Esse token precisa 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 considera que suas solicitações atuam em nome do seu aplicativo em vez de um usuário individual. O Cloud Firestore permite que essas solicitações ignorem as regras de segurança. Em vez disso, o Cloud Firestore usa o IAM para determinar se uma solicitação está autorizada.

É possível controlar as permissões de acesso das contas de serviço atribuindo papéis do IAM do Cloud Firestore.

Como autenticar com um token de acesso

Depois de receber um token de ID do Firebase ou um token do Google Identity OAuth 2.0, transmita o token para os endpoints do Cloud Firestore como um cabeçalho Authorization definido como Bearer {YOUR_TOKEN}.

Como fazer chamadas REST

Todos os endpoints 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, é preciso usar esta 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 testar a REST API é usar o API Explorer, que gera tokens do Google Identity OAuth 2.0 automaticamente e permite que você examine a API.

Métodos

A seguir, você encontrará descrições breves dos dois grupos de métodos mais importantes. Para conferir uma lista completa, consulte a Referência da API REST ou use o API Explorer (em inglês).

v1.projects.databases.documents

Execute operações CRUD nos documentos, semelhantes àquelas descritas nos guias Adicionar dados ou Receber dados.

v1.projects.databases.collectionGroups.indexes

Realize ações em índices, como criar novos índices, desativar um índice existente ou listar todos os índices atuais. Essa ação é útil para automatizar migrações de estrutura de dados ou sincronizar índices entre projetos.

Ela também permite a recuperação de metadados do documento, 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. Se a solicitação falhar, a API Cloud Firestore retornará 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 do erro. Esses códigos se aplicam às APIs REST e RPC do Cloud Firestore. Os SDKs e as bibliotecas de 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 uma confirmação não transacional:
repita a solicitação ou reestruture seu modelo de dados para reduzir a contenção.

Para solicitações em uma transação:
repita 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 já existente. Não tente novamente sem resolver o problema.
DEADLINE_EXCEEDED O servidor do Cloud Firestore que processa a solicitação ultrapassou um prazo. Tente novamente usando a espera exponencial.
FAILED_PRECONDITION A solicitação não atendeu a um dos pré-requisitos. Uma solicitação de consulta, por exemplo, pode exigir um índice ainda não definido. Para informações sobre o pré-requisito que falhou, consulte o campo da mensagem na resposta de erro. Não tente novamente sem resolver o problema.
INTERNAL O servidor do Cloud Firestore retornou um erro. Não tente executar essa solicitação mais de uma vez.
INVALID_ARGUMENT Um parâmetro de solicitação inclui um valor inválido. Para informações sobre o valor inválido, consulte o campo de mensagem na resposta de erro. 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 essa solicitação. Não tente novamente sem resolver o problema.
RESOURCE_EXHAUSTED O projeto ultrapassou a cota ou a capacidade de região/multirregião. Verifique se você não ultrapassou a cota do projeto. Se você ultrapassou a cota do projeto, não faça uma nova tentativa sem corrigir o problema.

Caso contrário, tente novamente com a 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 do Cloud Firestore retornou um erro. Tente novamente usando a espera exponencial.