Ir para o console

Usar a API REST do Configuração remota

Veja neste documento como usar a API REST do Configuração remota para ler e modificar o conjunto de parâmetros e condições em formato JSON, conhecido como o modelo do Configuração remota. Dessa forma, você gerencia o modelo de maneira programática com a aplicação de alterações no back-end que o app cliente pode buscar usando a biblioteca de cliente.

Com esta API, você ignora o gerenciamento do modelo no console do Configuração remota e integrar as respectivas alterações diretamente nos seus próprios processos. Faça as seguintes ações com a API REST do Configuração remota, por exemplo:

  • Agendar atualizações do Configuração remota: ao usar a API REST junto com um cron job, você altera os valores do Configuração remota em uma programação regular.
  • Importar valores de configuração em lotes: realize esta ação para fazer a transação de modo eficiente do seu próprio sistema para o Configuração remota do Firebase.
  • Usar o Configuração remota com o Cloud Functions para Firebase: você altera valores no seu app com base em eventos que acontecem no servidor. Por exemplo, você pode usar o Configuração remota para promover um novo recurso no seu app e desativar a promoção quando perceber que um número suficiente de pessoas já interagiu com a nova função.

As seguintes seções deste guia detalham as etapas obrigatórias para dar os primeiros passos com a API REST do Configuração remota. Caso prefira apenas executar o código e inspecioná-lo, consulte um dos apps de amostra que demonstram o uso da API REST do Configuração remota:

Primeiros passos com a API REST do Configuração remota

As etapas desta seção detalham como ter acesso a um modelo do Configuração remota e como modificá-lo com a API.

Etapa 1: defina valores no Console do Firebase

Normalmente, o primeiro passo é a configuração de valores no Console do Firebase. Neste guia, vamos supor que você tenha configurado o app de amostra do guia de início rápido do Configuração remota para iOS ou Android. Para esse app, você só precisa adicionar os dois parâmetros a seguir ao Console do Firebase:

Chave de parâmetro Valor padrão Observações
welcome_message Welcome to this sample app Altere para usar uma mensagem diferente de boas-vindas.
welcome_message_caps false Defina como true para que a mensagem de boas-vindas seja exibida em maiúsculas.

Etapa 2: receba um token de acesso para autenticar e autorizar solicitações da API

Os projetos do Firebase oferecem suporte a contas de serviço do Google, que você pode usar para chamar APIs do servidor do Firebase do seu servidor de aplicativos ou de um ambiente confiável. Se você estiver desenvolvendo código ou implantando o app localmente, é possível usar credenciais recebidas por meio dessa conta de serviço para autorizar solicitações do servidor.

Para autenticar uma conta de serviço e autorizá-la para acessar os serviços do Firebase, gere um arquivo de chave privada no formato JSON.

Para gerar um arquivo de chave privada da conta de serviço, siga estas etapas:

  1. No Console do Firebase, abra Configurações > Contas de serviço.

  2. Clique em Gerar nova chave privada e selecione Gerar chave para confirmar.

  3. Armazene com segurança o arquivo JSON que contém a chave.

Ao autorizar por meio de uma conta de serviço, existem duas opções para fornecer as credenciais ao seu aplicativo. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS ou transmita explicitamente o caminho para a chave da conta de serviço no código. A primeira opção é mais segura e é altamente recomendável.

Para definir a variável de ambiente:

Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, defina a variável novamente.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

Com o PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Depois de concluir as etapas acima, o Application Default Credentials (ADC) pode determinar implicitamente suas credenciais, permitindo que você use as credenciais da conta de serviço ao testar ou executar em ambientes que não são do Google.

Use suas credenciais do Firebase na Biblioteca de cliente da API Google para sua linguagem preferida e recupere um token de acesso do OAuth 2.0 de curta duração:

node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    var key = require('./service-account.json');
    var jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token

Java

private static String getAccessToken() throws IOException {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}

O método de atualização de token é chamado automaticamente para recuperar um token atualizado após o de acesso expirar.

Para autorizar o acesso ao Configuração remota, solicite o escopo https://www.googleapis.com/auth/firebase.remoteconfig.

Etapa 3: receba JSON do Configuração remota com a API

Em seguida, use a API para receber a versão ativa do modelo do Configuração remota em formato JSON. Para fazer isso, use o comando a seguir e substitua o próprio ID do projeto, disponível no Painel de configurações do console do Firebase para <my-project-id>:

curl comando:

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

Este comando exporta o payload do JSON para um arquivo e os cabeçalhos (incluindo a ETag) para um arquivo separado.

Solicitação HTTP bruta:

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

Essa chamada de API retorna o JSON a seguir, além de um cabeçalho separado que inclui uma ETag a ser usada na próxima solicitação. O exemplo a seguir mostra o JSON retornado:

{
  "parameters":[
    {
      "key":"welcome_message",
      "value_options":[
        {
          "value":"Welcome to this sample app"
        }
      ]
    },
    {
      "key":"welcome_message_caps",
      "value_options":[
        {
          "value":"false"
        }
      ]
    }
  ],
  "version":{
    "version_number": "42",
    "update_time":"2018-05-11T18:46:40Z",
    "update_user":{
      "name":"Jane Developer",
      "email":"jane@developer.org",
      "imageUrl":"http://image.google.com/path-to-profile-photo-for-jane"
    },
    "description":"Adding welcome messages",
    "update_origin":"CONSOLE",
    "update_type":"INCREMENTAL_UPDATE"
  }
}

Etapa 4: adicione condições aos dados JSON

Adicione algumas condições e valores condicionais que atualizarão o app de amostra para:

  • exibir uma mensagem ligeiramente diferente (com a palavra "novo" adicionada) para 10% dos usuários;
  • exibir a mensagem em letras maiúsculas para usuários nos Estados Unidos ou no Reino Unido.

Para estender o JSON dessa maneira, crie um arquivo contendo o seguinte:

{
  "conditions": [{
    "name": "android_english",
    "expression": "device.os == 'android' && device.country in ['us', 'uk']",
    "tagColor": "BLUE"
  }, {
    "name": "tenPercent",
    "expression": "percent <= 10",
    "tagColor": "BROWN"
  }],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "tenPercent": {
          "value": "Welcome to this new sample app"
        }
      },
      "description": "The sample app's welcome message"
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      },
      "conditionalValues": {
        "android_english": {
          "value": "true"
        }
      },
      "description": "Whether the welcome message should be displayed in all capital letters."
    }
  }
}

O JSON mostrado acima define primeiro um conjunto de condições e, depois, os valores padrão e os valores de parâmetros baseados em condição, ou seja, valores condicionais para cada parâmetro. Além disso, ele adiciona uma descrição opcional para cada elemento. Como comentários de código, eles são usados pelo desenvolvedor e não são exibidos no aplicativo. Uma ETag também é fornecida em um cabeçalho separado para fins de controle de versão.

A API REST do Configuração remota fornece várias condições e operadores de comparação que podem ser usados para alterar o comportamento e a aparência do seu app. Para saber mais sobre as condições e os operadores aceitos nessas condições, consulte a referência de expressão condicional.

Etapa 5: publique dados JSON para substituir dados no Configuração remota

Após criar um arquivo JSON para atualizar o modelo do Configuração remota, publique-o adicionando o JSON mostrado acima ao comando abaixo e substitua a configuração atual. Essa operação substitui todo o modelo de configuração pelo arquivo atualizado e o novo modelo ativo recebe um número de versão um número maior que o modelo que ele substituiu.

Para o comando curl, é possível simplesmente especificar o conteúdo usando o caractere "@" seguido do nome do arquivo.

Se necessário, reverta para a versão anterior. Para reduzir o risco de erros em uma atualização, valide antes de publicar.

curl comando:

curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -d @filename

Solicitação HTTP bruta:

Host: firebaseremoteconfig.googleapis.com
PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1
Content-Length: size
Content-Type: application/json; UTF8
Authorization: Bearer token
If-Match: expected ETag
Accept-Encoding: gzip
JSON_HERE

Como esta é uma solicitação de gravação, a ETag é modificada por esse comando e uma ETag atualizada é fornecida nos cabeçalhos da resposta ao próximo comando PUT.

Validar antes da publicação

Se preferir, valide suas atualizações antes de publicá-las anexando à sua solicitação de publicação o parâmetro de URL ?validate_only=true Na resposta, um código de status 200 e uma ETag atualizada com o sufixo -0 significa que sua atualização foi validada com êxito. Qualquer resposta que não tenha o código 200 indica que os dados JSON contêm erros que precisam ser corrigidos antes da publicação.

Códigos de erro

Código de status Significado
200 Atualizado com sucesso.
400 Ocorreu um erro de validação. Por exemplo, uma solicitação que contém mais do que o número de chaves permitido (2.000) retorna o código 400 (Solicitação inválida) com a mensagem de erro Param count too large.
401 Ocorreu um erro de autorização. Isso significa que nenhum token de acesso foi fornecido ou a API REST do Configuração remota do Firebase não foi adicionada ao seu projeto no Console para desenvolvedores do Cloud.
403 Ocorreu um erro de autenticação. O token de acesso fornecido está incorreto.
409 Esse código de status HTTPS pode ocorrer em duas situações:
  • Ocorreu um erro de incompatibilidade de versão porque o conjunto de valores e condições foi atualizado após a última vez em que você recuperou um valor de ETag. Para resolver esse problema, você deve usar um comando GET para receber um novo modelo e valor de ETag e, depois, atualize e envie o modelo.
  • Um comando PUT (solicitação de modelo atualizado do Configuração remota) foi usado sem a especificação de um cabeçalho If-Match.
500 Ocorreu um erro interno. Se esse erro ocorrer, envie um tíquete de suporte para o Firebase.

Um código de status 200 indica que o modelo do Configuração remota (parâmetros, valores e condições do projeto) foi atualizado e agora está disponível para apps que usam esse projeto. Outros códigos de status indicam que o modelo do Configuração remota de antes ainda está em vigor.

Depois de enviar atualizações para seu modelo, acesse o Console do Firebase e verifique se as alterações estão sendo exibidas conforme o esperado. Esta ação é fundamental, já que a ordem das condições afeta o modo como elas são definidas. A primeira condição que tiver uma definição true entrará em vigor.

Uso de ETag e atualizações forçadas

A API REST do Configuração remota usa uma tag de entidade (ETag) para evitar que ocorram condições de corrida e sobreposições das atualizações nos recursos. Para saber mais sobre ETags, acesse ETag – HTTP (em inglês).

O Google recomenda que você armazene em cache a ETag fornecida pelo comando GET mais recente e use o valor dela no cabeçalho da solicitação If-Match ao emitir comandos PUT. Se o comando PUT resultar em um código de status HTTPS 409, emita um novo comando GET para receber uma nova ETag e um novo modelo a ser usado com seu próximo comando PUT.

É possível contornar a ETag e a proteção que ela fornece. Para isso, basta forçar a atualização do modelo do Configuração remota da seguinte forma: If-Match: * No entanto, essa abordagem não é recomendada porque você correrá o risco de perder as atualizações do seu modelo caso vários clientes estejam atualizando o modelo do Configuração remota. Esse tipo de conflito poderá ocorrer se vários clientes estiverem usando a API ou se houver atualizações conflitantes de clientes de APIs e usuários do Console do Firebase.

Para ver orientações sobre o gerenciamento de versões de modelos do Configuração remota, consulte Modelos e controle de versão do Configuração remota.