Configurar e gerenciar um projeto do Firebase usando a API Management REST

A API Firebase Management REST permite configurar e gerenciar projetos do Firebase de maneira programática, incluindo os recursos e apps de um projeto.

Nesta visão geral, descrevemos o fluxo de trabalho para adicionar recursos e apps do Firebase a um projeto do Google Cloud que não usa esses itens.

Pule para seções específicas desta página se você quiser apenas:

Antes de seguir qualquer etapa nesta página, verifique se você ativou a API.

Para ver informações sobre o gerenciamento de acesso da API Firebase Management, confira a documentação da API Cloud Identity Access Management (IAM).

Antes de começar

Primeiro, você precisa ativar a API Management no projeto do Google Cloud e gerar seu token de acesso.

Ativar a API Management REST no projeto do Google Cloud

Caso você ainda não tenha ativado a API Firebase Management no seu projeto, será necessário fazer isso.

  1. Abra a página da API Firebase Management no Console de APIs do Google.
  2. Quando solicitado, selecione o projeto do Google Cloud.
  3. Clique em Ativar na página da API Firebase Management.

Gerar seu token de acesso à API

Veja abaixo um exemplo para Node.js sobre como recuperar seu token de acesso.

Primeiro, se você não estiver usando um ambiente do Google Cloud, defina a variável GOOGLE_APPLICATION_CREDENTIALS como o caminho para sua chave da conta de serviço.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"

Windows

Com o PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\service-account-file.json"

Em seguida, use o SDK Admin do Firebase para receber um token de acesso das credenciais da sua conta de serviço:

const admin = require('firebase-admin');

function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}

Encontrar o nome de recurso do seu projeto

É possível identificar os projetos do Google Cloud que podem receber serviços do Firebase.

SOLICITAÇÃO

Chame availableProjects.list. O corpo da solicitação dessa chamada precisa estar vazio.

Veja abaixo um exemplo para Node.js sobre como solicitar uma lista de projetos disponíveis do Google Cloud:

const fetch = require('node-fetch');

async function listProjects() {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/availableProjects';
  const options = {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    const projects = resp['projectInfo'];
    console.log('Project total: ' + projects.length);
    console.log('');
    for (let i in projects) {
      const project = projects[i];
      console.log('Project ' + i);
      console.log('ID: ' + project['project']);
      console.log('Display Name: ' + project['displayName']);
      console.log('');
    }
  } catch(err) {
    console.error(err);
  }
}

RESULTADO

O corpo da resposta de uma chamada para availableProjects.list contém uma lista de objetos ProjectInfo. Se a lista de projetos for muito longa, o corpo da resposta também conterá um nextPageToken que pode ser usado como um parâmetro de consulta para conseguir a próxima página de projetos.

Veja um exemplo de corpo de resposta de uma chamada para availableProjects.list:

{
  "projectInfo": [
    {
      "project": "projects/first-cloud-project",
      "displayName": "First Cloud Project"
    },
    {
      "project": "projects/second-cloud-project",
      "displayName": "Second Cloud Project"
    }
  ]
}

Essa resposta de exemplo tem dois projetos do Google Cloud que podem receber serviços do Firebase. Observe que o campo project fornece o nome de recurso globalmente exclusivo de um projeto.

Use qualquer valor de project listado na resposta de availableProjects.list para adicionar serviços ou apps do Firebase ao projeto.

Na próxima seção, adicionaremos serviços do Firebase ao First Cloud Project usando o nome de recurso projects/first-gcp-project.

Adicionar serviços do Firebase ao seu projeto

Os projetos do Google Cloud podem aproveitar os serviços oferecidos pelo Firebase. Nesta seção, você aprenderá como adicionar esses serviços ao seu projeto do Google Cloud de maneira programática. Também é possível fazer isso usando o Console do Firebase.

SOLICITAÇÃO

Chame projects.addFirebase. O corpo da solicitação dessa chamada precisa estar vazio.

Veja abaixo um exemplo para Node.js sobre como adicionar serviços do Firebase ao projeto do Google Cloud:

const fetch = require('node-fetch');

async function addFirebase(projectId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + ':addFirebase';
  const options = {
    method: 'POST',
    // Use a manual access token here since explicit user access token is required.
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

RESULTADO

O resultado de uma chamada para projects.addFirebase é uma Operation. Antes de chamar para seu projeto outros endpoints relacionados ao Firebase, a operação precisa ser concluída com sucesso.

Para verificar se isso aconteceu, chame operations.get na operação até que o valor de done seja true e a response seja do tipo FirebaseProject. Se a operação falhar, o error dela será definido como google.rpc.Status.

Este é o corpo da resposta de uma chamada para operations.get:

{
  "name": "operations/...",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.FirebaseProject",
    "projectId": "first-cloud-project",
    "projectNumber": "...",
    "displayName": "First Cloud Project",
    "name": "projects/first-cloud-project",
    "resources": {
      "hostingSite": "first-cloud-project",
      "realtimeDatabaseInstance": "first-cloud-project"
    }
  }
}

Como done é true, e o tipo de response é um FirebaseProject, o projeto do Google Cloud agora tem serviços do Firebase. A resposta também contém outras informações úteis sobre o FirebaseProject recém-criado, como o projectNumber e o resources padrão. A Operation será excluída automaticamente após a conclusão.

Adicionar apps do Firebase ao seu projeto

Muitos aplicativos diferentes podem usar um FirebaseProject, incluindo os para iOS, Android ou Web. Nesta seção, você aprenderá como adicionar apps do Firebase ao seu FirebaseProject de maneira programática. Também é possível fazer isso usando o Console do Firebase.

Selecione um tipo de app do Firebase para adicionar ao seu projeto.

É possível adicionar um app Android do Firebase ao seu projeto.

SOLICITAÇÃO

Chame projects.androidApps.create. Veja como construir o corpo da solicitação:

  • Obrigatório:

    • packageName: o nome do pacote canônico do app Android como seria mostrado no Google Play Console.
  • Opcional, mas recomendado:

    • displayName: o nome de exibição atribuído pelo usuário ao app. Esse valor é útil para encontrar o aplicativo no Console do Firebase.

No corpo da solicitação do nosso exemplo, usamos um packageName e um displayName:

{
  "displayName": "My Firebase Android App"
  "packageName": "com.firebase.android"
}

Veja um exemplo para Node.js sobre como adicionar um app Android do Firebase ao seu projeto:

const fetch = require('node-fetch');

async function addAndroidApp(projectId, displayName, packageName) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + '/androidApps';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'displayName': displayName,
      'packageName': packageName
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

RESULTADO

O resultado de uma chamada para projects.androidApps.create é uma Operation. Antes de chamar para seu projeto outros endpoints relacionados ao Firebase, a operação precisa ser concluída com sucesso.

Para verificar se isso aconteceu, chame operations.get na operação até que o valor de done seja true e a response seja do tipo AndroidApp. Se a operação falhar, o error dela será definido como google.rpc.Status.

Este é o corpo da resposta de uma chamada para operations.get:

{
  "name": "operations/...",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.AndroidApp",
    "name": "projects/first-cloud-project/androidApps/...",
    "appId": "...",
    "displayName": "My Firebase Android App",
    "projectId": "first-cloud-project",
    "packageName": "com.firebase.android"
  }
}

Como done é true e o tipo de response é um AndroidApp, o FirebaseProject agora tem um AndroidApp. A resposta também contém outras informações úteis sobre seu app Android do Firebase recém-criado, como o appId exclusivo. A Operation será excluída automaticamente após a conclusão.

Adicionar certificados SHA

É possível adicionar certificados SHA a qualquer app Android do Firebase. Para isso, chame projects.androidApps.sha.create. O corpo da solicitação para essa chamada de método precisa ter um campo name vazio. O resultado dessa chamada é uma instância recém-criada do ShaCertificate.

Ao chamar projects.androidApps.sha.create, você precisa fornecer um hash de certificado válido SHA-1 ou SHA-256. É possível retornar o hash SHA do certificado de assinatura com o comando signingReport do Gradle:

./gradlew signingReport

Para mais informações, consulte APIs do Google para Android.

É possível vincular uma conta do Google Analytics ao seu FirebaseProject de forma programática. Também é possível fazer isso na guia Integrações das Configurações do projeto.

A chamada para projects.addGoogleAnalytics requer um analytics_resource, que pode ser um analyticsAccountId ou um analyticsPropertyId:

  • Especifique um analyticsAccountId para provisionar uma nova propriedade do Google Analytics na conta especificada e associar a nova propriedade ao seu projeto do Firebase.

  • Especifique um analyticsPropertyId para associar a propriedade do Google Analytics ao projeto do Firebase.

É possível encontrar seu analyticsAccountId e qualquer analyticsPropertyId existente no site do Google Analytics.

Quando você chama projects.addGoogleAnalytics, isto acontece:

  1. A primeira verificação determina se algum fluxo de dados na propriedade do Google Analytics corresponde a um app do Firebase no seu FirebaseProject (com base no packageName ou no bundleId associado ao fluxo de dados). Em seguida, os fluxos de dados e os apps são vinculados, conforme aplicável. Esse processo automático só é feito em apps Android e iOS.

  2. Se nenhum fluxo de dados correspondente for encontrado para seus apps do Firebase, novos fluxos de dados serão provisionados na propriedade do Google Analytics para cada um dos aplicativos. Saiba que um novo fluxo de dados é sempre provisionado para um app da Web, mesmo que ele tenha sido associado anteriormente a um fluxo de dados na sua propriedade do Analytics.

Para saber mais sobre a hierarquia e a estrutura das contas do Google Analytics, acesse a documentação desse produto.

SOLICITAÇÃO

Chame projects.addGoogleAnalytics.

No corpo da solicitação da chamada de exemplo para project.addGoogleAnalytics, especificamos o analyticsAccountId da conta do Google Analytics. Essa chamada provisiona uma nova propriedade do Google Analytics e associa esse item ao FirebaseProject.

{
  "analyticsAccountId": "<your-google-analytics-account-id>"
}

Veja abaixo um exemplo para Node.js sobre como vincular um projeto do Firebase a uma conta do Google Analytics:

const fetch = require('node-fetch');

async function addGoogleAnalytics(projectId, analyticsAccountId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + ':addGoogleAnalytics';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'analyticsAccountId': analyticsAccountId
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

RESULTADO

O resultado de uma chamada para projects.addGoogleAnalytics é uma Operation. Antes de chamar para seu projeto outros endpoints relacionados ao Firebase, a operação precisa ser concluída com sucesso.

Para verificar se isso aconteceu, chame operations.get na operação até que o valor de done seja true e a response seja do tipo analyticsDetails. Se a operação falhar, o error dela será definido como google.rpc.Status.

Este é o corpo da resposta de uma chamada para operations.get:

{
  "name": "operations/...",
  "none": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.AnalyticsDetails",
    "analyticsProperty": [
      {
        "id": "...",
        "displayName": "..."
      }
    ],
    "streamMappings": [
      {
        "app": "...",
        "streamId": "...",
        "measurementId": "..."
      }
    ]
  }
}

Como done é "true" e o tipo de response é analyticsDetails, o FirebaseProject agora está vinculado à conta especificada do Google Analytics. A Operation será excluída automaticamente após a conclusão.

Determinar o local padrão do seu projeto (opcional)

Se o projeto do Firebase usar o Cloud Firestore, o Cloud Storage ou um aplicativo do App Engine, será possível determinar de forma programática o local padrão dos recursos do Google Cloud Platform (GCP) para seu projeto. Também é possível selecionar um local no Console do Firebase.

Antes de definir isso, consulte Selecionar locais para seu projeto e confira informações sobre a melhor opção para você. Também é preciso chamar projects.availableLocations para conseguir uma lista dos locais válidos para o projeto, porque se ele fizer parte de uma organização do Google Cloud, as políticas da organização poderão restringir quais locais serão válidos para o projeto.

Chamar o método defaultLocation.finalize cria um aplicativo do App Engine com um bucket padrão do Cloud Storage localizado no locationId fornecido no corpo da solicitação.

Se o Project já tem um aplicativo do App Engine ou se o método defaultLocation.finalize já foi chamado, então o local padrão dos recursos do GCP já está especificado.

SOLICITAÇÃO

Chame projects.defaultLocation.finalize. Veja como construir o corpo da solicitação:

  • Obrigatório:

    • locationId: o local onde são armazenados os dados dos serviços do GCP que exigem uma configuração de local, como o Cloud Firestore ou o Cloud Storage.
{
  "locationId": "us-west2"
}

Veja abaixo um exemplo para Node.js sobre como determinar o local padrão do projeto:

const fetch = require('node-fetch');

async function finalizeProjectLocation(projectId, locationId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + '/defaultLocation:finalize';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'locationId': locationId
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

RESULTADO

O resultado de uma chamada para projects.defaultLocation.finalize é uma Operation. Antes de chamar para seu projeto outros endpoints relacionados ao Firebase, a operação precisa ser concluída com sucesso.

Para verificar se isso aconteceu, chame operations.get na operação até que o valor de done seja true e a response seja do tipo google.protobuf.Empty. Se a operação não for bem-sucedida, o error no corpo da resposta será do tipo google.rpc.Status. A Operation será excluída automaticamente após a conclusão.