Automatize o gerenciamento de recursos

É possível automatizar a criação do banco de dados do Firestore com o seguinte processo:

Crie um novo projeto do Google Cloud. Cada projeto é limitado a um banco de dados do Firestore.
Crie um aplicativo do App Engine. O Firestore depende do App Engine. É necessário ativar o App Engine para usar o Firestore.
Crie um banco de dados do Firestore.

Nesta página, descrevemos como concluir esse processo usando as APIs REST, a ferramenta de linha de comando gcloud e a Terraform.

Criar um banco de dados com APIs REST

É possível provisionar um banco de dados do Firestore usando as APIs Resource Manager e App Engine Admin.

Autenticação e autorização

Para acessar as APIs Resource Manager e App Engine, autentique sua solicitação com um token de acesso. O token de acesso exige um escopo do OAuth 2.0 de:

https://www.googleapis.com/auth/cloud-platform

Para configurar a autenticação de um aplicativo, consulte Como configurar a autenticação em aplicativos de produção de servidor para servidor.

Ao desenvolver e testar o aplicativo, é possível obter um token de acesso usando:

gcloud auth application-default print-access-token.

autorização

A conta de usuário ou de serviço autenticada precisa da permissão resourcemanager.projects.create para criar um novo projeto. O papel "Criador de projetos" do IAM, por exemplo, concede essa permissão.

Para conceder esse papel, consulte Como conceder, alterar e revogar acesso a recursos.

Criar um novo projeto e banco de dados

Use o método projects.create para iniciar uma operação de criação de projeto. No corpo da solicitação, defina um recurso Project, por exemplo:
HTTP
```
POST https://cloudresourcemanager.googleapis.com/v1/projects HTTP/1.1

Authorization: Bearer access-token
Accept: application/json
Content-Type: application/json

{
  "projectId": "project-id"
}
      
```
Substitua:
- access-token é um token de acesso autenticado.
- project-id é um ID do projeto exclusivo.
Se for bem-sucedida, a solicitação retornará um nome de operação:
```
200:

{
  "name": "operations/cp.6311184959990822268"
}
    
```
Use o nome da operação da etapa anterior e o método operations.get do Resource Manager para confirmar a criação do projeto:
HTTP
```
GET https://cloudresourcemanager.googleapis.com/v1/operations/operation-name HTTP/1.1

Authorization: Bearer access-token
Accept: application/json
```
Quando a criação do projeto é bem-sucedida, a resposta inclui o seguinte campo:
```
"done": true,
      
```
Use o método apps.create da App Engine Admin API para criar um aplicativo do App Engine e um banco de dados do Firestore. No corpo da solicitação, defina um recurso de aplicativo e inclua o campo databaseType, por exemplo:
HTTP
```
POST https://appengine.googleapis.com/v1/apps HTTP/1.1

Authorization: Bearer access_token
Accept: application/json
Content-Type: application/json

{
  "databaseType": "CLOUD_FIRESTORE",
  "id": "project-id",
  "locationId": "location"
}
      
```
Observação: para criar um banco de dados do Firestore no modo Datastore , defina databaseType como CLOUD_DATASTORE_COMPATIBILITY.
Substitua:
- project-id é o ID do projeto que você criou.
- location define o local do aplicativo do App Engine e do banco de dados do Firestore. Depois de definido, não é possível alterar o local. Para ver uma lista completa de locais compatíveis, consulte Locais do App Engine.
  O App Engine e o Firestore são compatíveis com os mesmos locais, mas as regiões do App Engine a seguir são mapeadas para multirregiões do Firestore:
  - us-central (Iowa) cria um banco de dados do Firestore multirregional nam5 (Estados Unidos).
  - europe-west (Bélgica) cria um banco de dados do Firestore multirregional eur3 (Europa).
A solicitação retorna um nome de operação:
```
200:

{
  "name": "apps/project-id/operations/8612e502-4aeb-4f12-9e41-bbac0a0b819c",
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "method": "google.appengine.v1.Applications.CreateApplication",
    "insertTime": "2020-06-05T23:34:32.587Z",
    "user": "username",
    "target": "apps/project-id"
  }
}
        
```
Use o nome da operação da etapa anterior e apps.operations.get para confirmar a criação do banco de dados:
HTTP
```
GET https://appengine.googleapis.com/v1/operation-name HTTP/1.1

Authorization: Bearer access-token
Accept: application/json
    
```
Quando a operação for bem-sucedida, a resposta incluirá o campo a seguir:
```
"done": true,
      
```

Adicionar uma conta de faturamento e serviços do Firebase

Para associar programaticamente uma conta de faturamento ao projeto, use o método projects.updateBillingInfo.

Para ativar programaticamente os serviços do Firebase no projeto, consulte Configuração e gerenciamento de um projeto do Firebase usando a API REST Management.

Criar um banco de dados com a gcloud

É possível usar a ferramenta de linha de comando gcloud para automatizar a criação do banco de dados em um script do Bash ou do PowerShell. No script, conclua estas etapas:

Crie um novo projeto com gcloud projects create:
```
gcloud projects create project-id
```
Ative o App Engine com gcloud app create:
```
gcloud app create --region=region --project=project-id
```
onde region é o local do aplicativo do App Engine e do banco de dados do Firestore. Depois de definido, não é possível alterar o local. Para ver uma lista completa de locais compatíveis, consulte Locais do App Engine.

O App Engine e o Firestore são compatíveis com os mesmos locais, mas as seguintes regiões do App Engine são mapeadas para várias regiões do Firestore:
- us-central (Iowa) cria um banco de dados do Firestore multirregional nam5 (Estados Unidos).
- europe-west (Bélgica) cria um banco de dados do Firestore multirregional eur3 (Europa).

Ative a API Admin do App Engine com gcloud services enable:

gcloud services enable appengine.googleapis.com --project=project-id

Crie um banco de dados do Firestore com gcloud alpha firestore databases create ou gcloud alpha datastore databases create:
```
gcloud alpha firestore databases create --project=project-id --region=region
```
Para criar um banco de dados do Firestore em modo Datastore, use:
```
gcloud alpha datastore databases create --project=project-id --region=region
```
Para region, use o mesmo valor usado para ativar o App Engine.

Criar um banco de dados com o Terraform

Use o recurso google_firestore_database para provisionar um banco de dados do Firestore com o Terraform.

Por exemplo, o arquivo de configuração do Terraform a seguir cria um novo projeto e provisiona um banco de dados do Firestore:

firestore.tf

provider "google" {
  credentials = file("credentials-file")
}

resource "google_project" "my_project" {
  name       = "My Project"
  project_id = "project-id"
}

resource "google_project_service" "firestore" {
  project = google_project.my_project.project_id
  service = "firestore.googleapis.com"
}

resource "google_firestore_database" "database" {
  project     = google_project.my_project.project_id
  name        = "(default)"
  location_id = "location"
  type        = "FIRESTORE_NATIVE"

  depends_on = [google_project_service.firestore]
}

Substitua:

credentials-file é o caminho para o arquivo de chave da sua conta de serviço;
project-id é o ID do projeto; Os ID do projeto precisam ser exclusivos.
location é o local dos seus dois bancos de dados do Firestore. Não é possível mudar o local depois de configurar. Para uma lista completa de locais compatíveis, consulte Locais do Firestore.

Para usar o App Engine, utilize o recurso google_app_engine_application. Defina database_type como CLOUD_FIRESTORE ou CLOUD_DATASTORE_COMPATIBILITY.

provider "google" {
  credentials = file("credentials-file")
}

resource "google_project" "my_project" {
  name = "My Project"
  project_id = "project-id"
}

resource "google_app_engine_application" "app" {
  project     = google_project.my_project.project_id
  location_id = "location"
  database_type = "CLOUD_FIRESTORE"
}

us-central (Iowa) cria um banco de dados do Firestore multirregional nam5 (Estados Unidos).
europe-west (Bélgica) cria um banco de dados do Firestore multirregional eur3 (Europa).

Além disso, o Firestore está disponível em algumas regiões onde o App Engine não está.

Como criar índices no banco de dados

O banco de dados do Firestore pode incluir um índice de campo único ou um índice composto. É possível editar o arquivo de configuração do Terraform para criar um índice para o banco de dados.

Índice de campo único

O exemplo de arquivo de configuração do Terraform a seguir cria um índice de campo único no campo name na coleção chatrooms:

firestore.tf

resource "random_id" "variable"{
  byte_length = 8
}

resource "google_firestore_field" "single-index" {
  project = "project-id"
  database = "(default)"
  collection = "chatrooms_${random_id.variable.hex}"
  field = "name"

  index_config {
    indexes {
        order = "ASCENDING"
        query_scope = "COLLECTION_GROUP"
    }
    indexes {
        array_config = "CONTAINS"
    }
  }

  ttl_config {}
}

Substitua project-id pela ID do seu projeto. Os ID do projeto precisam ser exclusivos.

Índice composto

O exemplo de arquivo de configuração do Terraform a seguir cria um índice composto para uma combinação dos campos name e description na coleção chatrooms:

firestore.tf

resource "google_firestore_index" "composite-index" {
  project = "project-id"

  collection = "chatrooms"

  fields {
    field_path = "name"
    order      = "ASCENDING"
  }

  fields {
    field_path = "description"
    order      = "DESCENDING"
  }

}

Substitua project-id pela ID do seu projeto. Os ID do projeto precisam ser exclusivos.

Automatize o gerenciamento de recursos

Criar um banco de dados com APIs REST

Autenticação e autorização

autorização

Criar um novo projeto e banco de dados

HTTP

HTTP

HTTP

HTTP

Adicionar uma conta de faturamento e serviços do Firebase

Criar um banco de dados com a gcloud

Criar um banco de dados com o Terraform

firestore.tf

Como criar índices no banco de dados

Índice de campo único

Índice composto