Automatize o gerenciamento de recursos

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

  1. Crie um novo projeto do Google Cloud. Cada projeto é limitado a um banco de dados do Firestore.
  2. Crie um aplicativo do App Engine. O Firestore depende do App Engine. É necessário ativar o App Engine para usar o Firestore.
  3. 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

  1. 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:

    Se for bem-sucedida, a solicitação retornará um nome de operação: 

    200:

{
  "name": "operations/cp.6311184959990822268"
}

  2. 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,

  3. 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"
}

    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"
  }
}

  4. 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:

  1. Crie um novo projeto com gcloud projects create:

    gcloud projects create project-id

  2. 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).

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

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

  4. 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.