Ir para o console

Usar a Cloud Firestore REST API

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 REST API diretamente.

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

  • Ao acessar o Cloud Firestore a partir de 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, use a RPC API em vez da REST API.

Autenticação e autorização

Para fazer a autenticação, a Cloud Firestore REST API aceita um token de código 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 regras de segurança do Cloud Firestore para determinar se uma solicitação está autorizada.

  • 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 Cloud Identity and Access Management (Cloud IAM) para determinar se uma solicitação está autorizada.

Como usar tokens de código do Firebase

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

Ao recuperar o token de código do Firebase de um usuário, você pode fazer solicitações em nome do usuário.

Para solicitações autenticadas com um token de código do Firebase e para solicitações não autenticadas, o Cloud Firestore usa suas regras de segurança do Cloud Firestore 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 de APIs do Google ou siga as etapas em Como usar 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 print-access-token.

Esse token precisa ter o seguinte escopo para enviar solicitações para a Cloud Firestore REST API:

  • 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 suas regras de segurança. Em vez disso, o Cloud Firestore usa o Cloud Identity and Access Management (Cloud IAM) para determinar se uma solicitação está autorizada.

Para controlar as permissões de acesso das contas de serviço, atribua papéis de IAM do Cloud Firestore.

Como autenticar com um token de acesso

Depois de receber um token de código do Firebase ou um token do Google Identity OAuth 2.0, transfira-o para os pontos de extremidade do Cloud Firestore como um cabeçalho Authorization definido como Bearer {YOUR_TOKEN}.

Como fazer chamadas REST

Todos os pontos de extremidade da REST API estão sob o URL base https://firestore.googleapis.com/v1beta1/.

Para criar um caminho para um documento com o código LA na coleção cities sob o 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/v1beta1/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 ver uma lista completa, consulte a referência da REST API ou use o API Explorer.

v1beta1.projects.databases.documents

Execute operações do CRUD nos documentos, semelhantes às descritas nos guias sobre como adicionar dados ou receber dados.

v1beta1.projects.databases.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.