Reutilizar o código do Cloud Functions como uma extensão do Firebase

1. Antes de começar

Uma extensão do Firebase executa uma tarefa específica ou um conjunto de tarefas em resposta a solicitações HTTP ou acionamento de eventos de outros produtos do Firebase e do Google, como Firebase Cloud Messaging, Cloud Firestore ou Pub/Sub.

O que você vai criar

Neste codelab, você vai criar uma extensão do Firebase para geohashing. Depois de implantada, a extensão converte coordenadas X e Y em geohashes em resposta a eventos do Firestore ou por meio de invocações de funções chamáveis. Isso pode ser usado como uma alternativa a implementar a biblioteca geofire em todas as plataformas de destino para armazenar dados, economizando tempo.

A extensão de geohash mostrada no console do Firebase

O que você aprenderá

  • Como pegar o código do Cloud Functions e transformá-lo em uma extensão do Firebase distribuível
  • Como configurar um arquivo extension.yaml
  • Como armazenar strings sensíveis (chaves de API) em uma extensão
  • Como permitir que os desenvolvedores da extensão a configurem de acordo com as necessidades deles
  • Como testar e implantar a extensão

O que é necessário

  • CLI do Firebase (instalar e fazer login)
  • Uma Conta do Google, como uma conta do Gmail
  • Node.js e npm
  • Seu ambiente de desenvolvimento favorito

2. Começar a configuração

Buscar o código

Tudo o que você precisa para essa extensão está em um repositório do GitHub. Para começar, abra o código no ambiente de desenvolvimento de sua preferência.

  1. Descompacte o arquivo ZIP transferido por download.
  2. Para instalar as dependências necessárias, abra o terminal no diretório functions e execute o comando npm install.

Configurar o Firebase

Este codelab incentiva muito o uso de emuladores do Firebase. Se quiser testar o desenvolvimento de extensões com um projeto real do Firebase, consulte criar um projeto do Firebase. Este codelab usa o Cloud Functions. Portanto, se você estiver usando um projeto real do Firebase em vez dos emuladores, faça upgrade para o plano de preços Blaze.

Quer pular para frente?

Você pode baixar uma versão concluída do codelab. Se você tiver dificuldades ou quiser ver como fica uma extensão concluída, confira a ramificação codelab-end do repositório do GitHub ou faça o download do arquivo ZIP concluído.

3. Revisar o código

  • Abra o arquivo index.ts do arquivo ZIP. Observe que ele contém duas declarações do Cloud Functions.

O que essas funções fazem?

Essas funções de demonstração são usadas para geohashing. Eles pegam um par de coordenadas e o transformam em um formato otimizado para consultas geográficas no Firestore. As funções simulam o uso de uma chamada de API para que você possa aprender mais sobre como processar tipos de dados sensíveis em extensões. Para mais informações, consulte a documentação sobre execução de consultas geográficas em dados no Firestore.

Constantes de função

As constantes são declaradas no início, na parte de cima do arquivo index.ts. Algumas dessas constantes são referenciadas nos gatilhos definidos da extensão.

index.ts

import {firestore} from "firebase-functions";
import {initializeApp} from "firebase-admin/app";
import {GeoHashService, ResultStatusCode} from "./fake-geohash-service";
import {onCall} from "firebase-functions/v1/https";
import {fieldValueExists} from "./utils";

const documentPath = "users/{uid}";
const xField = "xv";
const yField = "yv";
const apiKey = "1234567890";
const outputField = "hash";

initializeApp();

const service = new GeoHashService(apiKey);

Gatilho do Firestore

A primeira função no arquivo index.ts é assim:

index.ts

export const locationUpdate = firestore.document(documentPath)
  .onWrite((change) => {
    // item deleted
    if (change.after == null) {
      return 0;
    }
    // double check that both values exist for computation
    if (
      !fieldValueExists(change.after.data(), xField) ||
      !fieldValueExists(change.after.data(), yField)
    ) {
      return 0;
    }
    const x: number = change.after.data()![xField];
    const y: number = change.after.data()![yField];
    const hash = service.convertToHash(x, y);
    // This is to check whether the hash value has changed. If
    // it hasn't, you don't want to write to the document again as it
    // would create a recursive write loop.
    if (fieldValueExists(change.after.data(), outputField)
      && change.after.data()![outputField] == hash) {
      return 0;
    }
    return change.after.ref
      .update(
        {
          [outputField]: hash.hash,
        }
      );
  });

Essa função é um gatilho do Firestore. Quando um evento de gravação ocorre no banco de dados, a função reage a ele pesquisando um campo xv e um campo yv. Se os dois campos existirem, ela vai calcular o geohash e gravar a saída em um local especificado de saída do documento. O documento de entrada é definido pela constante users/{uid}, o que significa que a função lê todos os documentos gravados na coleção users/ e processa um geohash para esses documentos. Em seguida, ele gera o hash em um campo de hash no mesmo documento.

Funções chamáveis

A próxima função no arquivo index.ts é assim:

index.ts

export const callableHash = onCall((data, context) => {
  if (context.auth == undefined) {
    return {error: "Only authorized users are allowed to call this endpoint"};
  }
  const x = data[xField];
  const y = data[yField];
  if (x == undefined || y == undefined) {
    return {error: "Either x or y parameter was not declared"};
  }
  const result = service.convertToHash(x, y);
  if (result.status != ResultStatusCode.ok) {
    return {error: `Something went wrong ${result.message}`};
  }
  return {result: result.hash};
});

Observe a função onCall. Isso indica que a função é chamável, ou seja, pode ser chamada no código do aplicativo cliente. Essa função chamável usa parâmetros x e y e retorna um geohash. Embora essa função não seja chamada diretamente neste codelab, ela está incluída aqui como um exemplo de algo a ser configurado na extensão do Firebase.

4. Configurar um arquivo extension.yaml

Agora que você sabe o que o código do Cloud Functions na sua extensão faz, já pode empacotar para distribuição. Cada extensão do Firebase vem com um arquivo extension.yaml que descreve o que a extensão faz e como ela se comporta.

Um arquivo extension.yaml exige alguns metadados iniciais sobre sua extensão. Cada uma das etapas a seguir ajuda você a entender o que todos os campos significam e por que você precisa deles.

  1. Crie um arquivo extension.yaml no diretório raiz do projeto que você baixou antes. Comece adicionando o seguinte:
name: geohash-ext
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version (do not edit)

O nome da extensão é usado como base do ID da instância da extensão. Os usuários podem instalar várias instâncias de uma extensão, cada uma com um ID próprio. Em seguida, o Firebase gera o nome das contas de serviço da extensão e dos recursos específicos dela usando esse ID de instância. O número da versão indica a versão da extensão. Ele precisa seguir o versionamento semântico, e você precisa atualizá-lo sempre que fizer mudanças na funcionalidade da extensão. A versão da especificação da extensão é usada para determinar qual especificação das Extensões do Firebase seguir. Nesse caso, v1beta é usado.

  1. Adicione alguns detalhes fáceis de entender ao arquivo YAML:
...

displayName: Latitude and longitude to GeoHash converter
description: A converter for changing your Latitude and longitude coordinates to geohashes.

O nome de exibição é uma representação amigável do nome da extensão quando os desenvolvedores interagem com ela. A descrição dá uma breve visão geral do que a extensão faz. Quando a extensão é implantada em extensions.dev, ela fica assim:

Extensão Geohash Converter, conforme mostrado em extensions.dev

  1. Especifique a licença do código na sua extensão.
...

license: Apache-2.0  # The license you want for the extension
  1. Indique quem escreveu a extensão e se o faturamento é necessário para instalá-la:
...

author:
  authorName: AUTHOR_NAME
  url: https://github.com/Firebase

billingRequired: true

A seção author é usada para informar aos usuários com quem entrar em contato caso eles tenham problemas com a extensão ou queiram mais informações sobre ela. billingRequired é um parâmetro obrigatório e precisa ser definido como true, já que todas as extensões dependem do Cloud Functions, que exige o plano Blaze.

Isso abrange o número mínimo de campos necessários no arquivo extension.yaml para identificar a extensão. Para mais detalhes sobre outras informações de identificação que podem ser especificadas em uma extensão, consulte a documentação.

5. Converter o código do Cloud Functions em um recurso de extensões

Um recurso de extensão é um item que o Firebase cria no projeto durante a instalação de uma extensão. A extensão passa a ser proprietária desses recursos e tem uma conta de serviço específica que opera neles. Neste projeto, esses recursos são o Cloud Functions, que precisa ser definido no arquivo extension.yaml porque a extensão não cria recursos automaticamente com base no código da pasta de funções. Se as funções do Cloud não forem declaradas explicitamente como um recurso, elas não poderão ser implantadas quando a extensão for implantada.

Local de implantação definido pelo usuário

  1. Permitir que o usuário especifique o local em que quer implantar essa extensão e decida se é melhor hospedar a extensão mais perto dos usuários finais ou do banco de dados. No arquivo extension.yaml, inclua a opção de escolher um local.

extension.yaml

Agora você está pronto para escrever a configuração do recurso de função.

  1. No arquivo extension.yaml, crie um objeto de recurso para a função locationUpdate. Anexe o seguinte ao arquivo extension.yaml:
resources:
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/users/{uid}

Defina name como o nome da função definido no arquivo index.ts do projeto. Você especifica o type da função que está sendo implantada, que sempre será firebaseextensions.v1beta.function, por enquanto. Em seguida, defina o properties dessa função. A primeira propriedade que você define é o eventTrigger associado a essa função. Para espelhar o que a extensão oferece suporte atualmente, use o eventType de providers/cloud.firestore/eventTypes/document.write, que está na documentação Escrever funções do Cloud para sua extensão. Você define resource como o local dos documentos. Como o objetivo atual é espelhar o que existe no código, o caminho do documento detecta users/{uid}, com o local padrão do banco de dados antes dele.

  1. A extensão precisa de permissões de leitura e gravação para o banco de dados do Firestore. No final do arquivo extension.yaml, especifique os papéis do IAM a que a extensão precisa ter acesso para trabalhar com o banco de dados no projeto do Firebase do desenvolvedor.
roles:
  - role: datastore.user
    reason: Allows the extension to read / write to your Firestore instance.

O papel datastore.user vem da lista de papéis do IAM compatíveis com extensões. Como a extensão vai ler e gravar, a função datastore.user é uma boa opção.

  1. A função de chamada também precisa ser adicionada. No arquivo extension.yaml, crie um novo recurso na propriedade "resources". Essas propriedades são específicas para uma função chamável:
  - name: callableHash
    type: firebaseextensions.v1beta.function
    properties:
      httpsTrigger: {}

Embora o recurso anterior tenha usado um eventTrigger, aqui você usa um httpsTrigger, que abrange funções chamáveis e HTTPS.

Verificação de código

Essa foi muita configuração para fazer com que o extension.yaml corresponda a tudo o que foi feito pelo código no arquivo index.ts. O arquivo extension.yaml concluído vai ficar assim:

extension.yaml

name: geohash-ext
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version (do not edit)

displayName: Latitude and Longitude to GeoHash converter
description: A converter for changing your Latitude and Longitude coordinates to geohashes.

license: Apache-2.0  # The license you want for the extension

author:
  authorName: Sparky
  url: https://github.com/Firebase

billingRequired: true

resources:
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/users/{uid}
  - name: callableHash
    type: firebaseextensions.v1beta.function
    properties:
      httpsTrigger: {}

roles:
  - role: datastore.user
    reason: Allows the extension to read / write to your Firestore instance.

Verificação de status

Neste ponto, você já tem as partes funcionais iniciais da extensão configuradas. Portanto, é possível testá-la usando os emuladores do Firebase.

  1. Se ainda não tiver feito isso, chame npm run build na pasta de funções do projeto de extensões baixado.
  2. Crie um novo diretório no sistema host e conecte-o ao projeto do Firebase usando firebase init.
cd ..
mkdir sample-proj
cd sample-proj
firebase init --project=projectID-or-alias

    This command creates a `firebase.json` file in the directory. In the following steps, you push the configuration specified in this file to Firebase.
  1. No mesmo diretório, execute firebase ext:install. Substitua /path/to/extension pelo caminho absoluto do diretório que contém o arquivo extension.yaml.
firebase ext:install /path/to/extension

    This command does two things:
  • Ele pede que você especifique a configuração da instância da extensão e cria um arquivo *.env que contém as informações de configuração da instância.
  • Ele adiciona a instância da extensão à seção extensions do seu firebase.json. Isso funciona como um mapa do ID da instância para a versão da extensão.
  • Como você está implantando o projeto localmente, pode especificar que quer usar um arquivo local em vez do Secret Manager do Google Cloud.

Captura de tela do processo de instalação da extensão mostrando que o arquivo local está sendo usado para secrets ao instalar essa extensão

  1. Inicie os emuladores do Firebase com a nova configuração:
firebase emulators:start
  1. Depois de executar emulators:start, navegue até a guia "Firestore" na visualização da Web dos emuladores.
  2. Adicione um documento à coleção users com um campo de número xv e um campo de número yv.

Uma caixa de diálogo mostrada nos emuladores do Firebase para iniciar uma coleção com o ID que contém a frase

  1. Se você tiver instalado a extensão, ela vai criar um novo campo chamado hash no documento.

A coleção de usuários com um documento de usuário que tem um campo xv, yv e hash.

Fazer uma limpeza para evitar conflitos

  • Depois de concluir o teste, desinstale a extensão. Você vai atualizar o código dela e não quer conflitos com a extensão atual mais tarde.

As extensões permitem que várias versões da mesma extensão sejam instaladas de uma só vez. Ao desinstalar, você garante que não haja conflitos com uma extensão instalada anteriormente.

firebase ext:uninstall geohash-ext

A solução atual funciona, mas, como mencionado no início do projeto, há uma chave de API codificada para simular a comunicação com um serviço. Como usar a chave de API do usuário final em vez da fornecida originalmente? Leia para saber mais.

6. Tornar a extensão configurável pelo usuário

Neste ponto do codelab, você tem uma extensão configurada para uso com a configuração opinativa das funções que já escreveu. Mas e se o usuário quiser usar latitude e longitude em vez de y e x para os campos que indicam a localização em um plano cartesiano? Além disso, como você pode fazer com que o usuário final forneça a própria chave de API em vez de usar a fornecida? Você pode exceder rapidamente a cota dessa API. Nesse caso, você configura e usa parâmetros.

Definir parâmetros básicos no arquivo extension.yaml

Comece convertendo os itens para os quais os desenvolvedores podem ter uma configuração personalizada. O primeiro seria os parâmetros XFIELD e YFIELD.

  1. No arquivo extension.yaml, adicione o seguinte código, que usa os parâmetros de campo XFIELD e YFIELD. Esses parâmetros ficam dentro da propriedade YAML params definida anteriormente:

extension.yaml

params:
  - param: XFIELD
    label: The X Field Name
    description: >-
      The X Field is also known as the **longitude** value. What does
      your Firestore instance refer to as the X value or the longitude
      value. If no value is specified, the extension searches for
      field 'xv'.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: xv
    required: false
    immutable: false
    example: xv
  - param: YFIELD
    label: The Y Field Name
    description: >-
      The Y Field is also known as the **latitude** value. What does
      your Firestore instance refer to as the Y value or the latitude
      value. If no value is specified, the extension searches for
      field 'yv'.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: yv
    required: false
    immutable: false
    example: yv
  • param nomeia o parâmetro de uma forma visível para você, o produtor da extensão. Use esse valor mais tarde ao especificar os valores dos parâmetros.
  • label é um identificador legível para o desenvolvedor saber o que o parâmetro faz.
  • description oferece uma descrição detalhada do valor. Como ele é compatível com Markdown, é possível vincular documentação extra ou destacar palavras importantes para o desenvolvedor.
  • type define o mecanismo de entrada para como um usuário define o valor do parâmetro. Há muitos tipos, incluindo string, select, multiSelect, selectResource e secret. Para saber mais sobre cada uma dessas opções, consulte a documentação.
  • validationRegex restringe a entrada do desenvolvedor a um determinado valor de regex. No exemplo, ela se baseia nas diretrizes simples de nome de campo encontradas aqui. Se isso falhar...
  • validationErrorMessage alerta o desenvolvedor sobre o valor de falha.
  • default é o valor que seria usado se o desenvolvedor não inserisse nenhum texto.
  • required significa que o desenvolvedor não precisa inserir nenhum texto.
  • imutável permite que o desenvolvedor atualize essa extensão e mude esse valor. Nesse caso, o desenvolvedor precisa poder mudar os nomes dos campos conforme os requisitos mudam.
  • O exemplo dá uma ideia de como pode ser uma entrada válida.

É muita coisa para entender!

  1. Você tem mais três parâmetros para adicionar ao arquivo extension.yaml antes de incluir um parâmetro especial.
  - param: INPUTPATH
    label: The input document to listen to for changes
    description: >-
      This is the document where you write an x and y value to. Once
      that document has received a value, it notifies the extension to
      calculate a geohash and store that in an output document in a certain
      field. This accepts function [wildcard parameters](https://firebase.google.com/docs/functions/firestore-events#wildcards-parameters)
    type: string
    validationRegex: ^[^/]+(/[^/]*/[^/]*)*/[^/]+$
    validationErrorMessage: >-
      This must point to a document path, not a collection path from the root
      of the database. It must also not start or end with a '/' character.
    required: true
    immutable: false
    example: users/{uid}
  - param: OUTPUTFIELD
    label: Geohash field
    description: >-
      This specifies the field in the output document to store the geohash in.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    required: false
    default: hash
    immutable: false
    example: hash

Definir parâmetros sensíveis

Agora, você precisa gerenciar a chave de API especificada pelo usuário. Essa é uma string sensível que não deve ser armazenada em texto simples na função. Em vez disso, armazene esse valor no Cloud Secret Manager. É um local especial na nuvem que armazena secrets criptografados e evita que eles sejam vazados acidentalmente. Isso exige que o desenvolvedor pague pelo uso desse serviço, mas adiciona uma camada extra de segurança às chaves de API e pode limitar atividades fraudulentas. A documentação do usuário alerta o desenvolvedor de que é um serviço pago para que não haja surpresas no faturamento. No geral, o uso é semelhante aos outros recursos de string mencionados acima. A única diferença é o tipo, que é chamado de secret.

  • No arquivo extension.yaml, adicione o seguinte código:

extension.yaml

  - param: APIKEY
    label: GeohashService API Key
    description: >-
      Your geohash service API Key. Since this is a demo, and not a real
      service, you can use : 1234567890.
    type: secret
    required: true
    immutable: false

Atualize os atributos resource para usar parâmetros

Como mencionado anteriormente, o recurso (não a função) define como ele é observado. Portanto, o recurso locationUpdate precisa ser atualizado para usar o novo parâmetro.

  • No arquivo extension.yaml, adicione o seguinte código:

extension.yaml

## Change from this
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/users/{uid}]

## To this
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/${INPUTPATH}

Verifique o arquivo extension.yaml

  • Revise o arquivo extension.yaml. O código será semelhante a este:

extension.yaml

name: geohash-ext
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version (do not edit)

displayName: Latitude and Longitude to GeoHash converter
description: A converter for changing your Latitude and Longitude coordinates to geohashes.

license: Apache-2.0  # The license you want to use for the extension

author:
  authorName: Sparky
  url: https://github.com/Firebase

billingRequired: true

params:
  - param: XFIELD
    label: The X Field Name
    description: >-
      The X Field is also known as the **longitude** value. What does
      your Firestore instance refer to as the X value or the longitude
      value. If you don't provide a value for this field, the extension will use 'xv' as the default value.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: xv
    required: false
    immutable: false
    example: xv
  - param: YFIELD
    label: The Y Field Name
    description: >-
      The Y Field is also known as the **latitude** value. What does
      your Firestore instance refer to as the Y value or the latitude
      Value. If you don't provide a value for this field, the extension will use 'yv' as the default value.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    default: yv
    required: false
    immutable: false
    example: yv
  - param: INPUTPATH
    label: The input document to listen to for changes
    description: >-
      This is the document where you write an x and y value to. Once
      that document has been modified, it notifies the extension to
      compute a geohash and store that in an output document in a certain
      field. This accepts function [wildcard parameters](https://firebase.google.com/docs/functions/firestore-events#wildcards-parameters)
    type: string
    validationRegex: ^[^/]+(/[^/]*/[^/]*)*/[^/]+$
    validationErrorMessage: >-
      This must point to a document path, not a collection path from the root
      of the database. It must also not start or end with a '/' character.
    required: true
    immutable: false
    example: users/{uid}
  - param: OUTPUTFIELD
    label: Geohash field
    description: >-
      This specifies the field in the output document to store the geohash in.
    type: string
    validationRegex: ^\D([0-9a-zA-Z_.]{0,375})$
    validationErrorMessage: >-
      The field can only contain uppercase or lowercase letter, numbers,
      _, and . characters and must be less than 1500 bytes long. The field
      must also not start with a number.
    required: false
    default: hash
    immutable: false
    example: hash
  - param: APIKEY
    label: GeohashService API Key
    description: >-
      Your geohash service API Key. Since this is a demo, and not a real
      service, you can use : 1234567890.
    type: secret
    required: true
    immutable: false

resources:
  - name: locationUpdate
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/cloud.firestore/eventTypes/document.write
        resource: projects/${PROJECT_ID}/databases/(default)/documents/${INPUTPATH}
  - name: callableHash
    type: firebaseextensions.v1beta.function
    properties:
      httpsTrigger: {}

roles:
  - role: datastore.user
    reason: Allows the extension to read / write to your Firestore instance.

Acessar parâmetros no código

Agora que todos os parâmetros estão configurados no arquivo extension.yaml, adicione-os ao arquivo index.ts.

  • No arquivo index.ts, substitua os valores padrão por process.env.PARAMETER_NAME, que busca os valores de parâmetros adequados e os preenche no código da função implantado no projeto do Firebase do desenvolvedor.

index.ts

// Replace this:
const documentPath = "users/{uid}";
const xField = "xv";
const yField = "yv";
const apiKey = "1234567890";
const outputField = "hash";

// with this:
const documentPath = process.env.INPUTPATH!; // this value is ignored since its read from the resource
const xField = process.env.XFIELD!;
const yField = process.env.YFIELD!;
const apiKey = process.env.APIKEY!;
const outputField = process.env.OUTPUTFIELD!;

Normalmente, você quer realizar verificações de nulo com os valores das variáveis de ambiente, mas, nesse caso, você confia que os valores dos parâmetros foram copiados corretamente. O código agora está configurado para funcionar com os parâmetros de extensão.

7. Criar documentação do usuário

Antes de testar o código em emuladores ou no marketplace de extensões do Firebase, a extensão precisa ser documentada para que os desenvolvedores saibam o que estão recebendo ao usá-la.

  1. Comece criando o arquivo PREINSTALL.md, que é usado para descrever a funcionalidade, os pré-requisitos para instalação e as possíveis implicações de faturamento.

PREINSTALL.md

Use this extension to automatically convert documents with a latitude and
longitude to a geohash in your database. Additionally, this extension includes a callable function that allows users to make one-time calls
to convert an x,y coordinate into a geohash.

Geohashing is supported for latitudes between 90 and -90 and longitudes
between 180 and -180.

#### Third Party API Key

This extension uses a fictitious third-party API for calculating the
geohash. You need to supply your own API keys. (Since it's fictitious,
you can use 1234567890 as an API key).

#### Additional setup

Before installing this extension, make sure that you've [set up a Cloud
Firestore database](https://firebase.google.com/docs/firestore/quickstart) in your Firebase project.

After installing this extension, you'll need to:

- Update your client code to point to the callable geohash function if you
want to perform arbitrary geohashes.

Detailed information for these post-installation tasks are provided after
you install this extension.

#### Billing
To install an extension, your project must be on the [Blaze (pay as you
go) plan](https://firebase.google.com/pricing)

- This extension uses other Firebase and Google Cloud Platform services,
which have associated charges if you exceed the service's no-cost tier:
 - Cloud Firestore
 - Cloud Functions (Node.js 16+ runtime. [See
FAQs](https://firebase.google.com/support/faq#extensions-pricing))
 - [Cloud Secret Manager](https://cloud.google.com/secret-manager/pricing)
  1. Para economizar tempo na gravação do README.md deste projeto, use o método de conveniência:
firebase ext:info . --markdown > README.md

Isso combina o conteúdo do arquivo PREINSTALL.md e outros detalhes sobre a extensão do arquivo extension.yaml.

Por fim, informe ao desenvolvedor da extensão alguns detalhes adicionais sobre a extensão que acabou de ser instalada. O desenvolvedor pode receber mais instruções e informações depois de concluir a instalação, além de tarefas detalhadas pós-instalação, como configurar o código do cliente.

  1. Crie um arquivo POSTINSTALL.md e inclua as seguintes informações pós-instalação:

POSTINSTALL.md

Congratulations on installing the geohash extension!

#### Function information

* **Firestore Trigger** - ${function:locationUpdate.name} was installed
and is invoked when both an x field (${param:XFIELD}) and y field
(${param:YFIELD}) contain a value.

* **Callable Trigger** - ${function:callableHash.name} was installed and
can be invoked by writing the following client code:
 ```javascript
import { getFunctions, httpsCallable } from "firebase/functions";
const functions = getFunctions();
const geoHash = httpsCallable(functions, '${function:callableHash.name}');
geoHash({ ${param:XFIELD}: -122.0840, ${param:YFIELD}: 37.4221 })
  .then((result) => {
    // Read result of the Cloud Function.
    /** @type {any} */
    const data = result.data;
    const error = data.error;
    if (error != null) {
        console.error(`callable error : ${error}`);
    }
    const result = data.result;
    console.log(result);
  });

Monitoramento

Como prática recomendada, monitore a atividade da extensão instalada, incluindo verificações de integridade, uso e registros.

The output rendering looks something like this when it's deployed:

<img src="img/82b54a5c6ca34b3c.png" alt="A preview of the latitude and longitude geohash converter extension in the firebase console"  width="957.00" />


## Test the extension with the full configuration
Duration: 03:00


It's time to make sure that the user-configurable extension is working the way it is intended.

* Change into the functions folder and ensure that the latest compiled version of the extensions exists. In the extensions project functions directory, call:

```console
npm run build

Isso recompila as funções para que o código-fonte mais recente esteja pronto para implantação junto com a extensão quando ela for implantada em um emulador ou diretamente no Firebase.

Em seguida, crie um novo diretório para testar a extensão. Como a extensão foi desenvolvida com base em funções existentes, não faça testes na pasta em que ela foi configurada, porque isso também tenta implantar as funções e as regras do Firebase.

Instalar e testar com os emuladores do Firebase

  1. Crie um novo diretório no sistema host e conecte-o ao projeto do Firebase usando firebase init.
mkdir sample-proj
cd sample-proj
firebase init --project=projectID-or-alias
  1. Nesse diretório, execute firebase ext:install para instalar a extensão. Substitua /path/to/extension pelo caminho absoluto do diretório que contém o arquivo extension.yaml. Isso inicia o processo de instalação da extensão e cria um arquivo .env que contém as configurações antes de enviar a configuração para o Firebase ou para os emuladores.
firebase ext:install /path/to/extension
  • Como você está implantando o projeto localmente, especifique que quer usar um arquivo local em vez do Secret Manager do Google Cloud.

da928c65ffa8ce15.png

  1. Inicie o Pacote de emuladores locais:
firebase emulators:start

Instalar e testar com um projeto real do Firebase

É possível instalar sua extensão em um projeto real do Firebase. Recomendamos o uso de um projeto de teste. Use esse fluxo de trabalho se quiser testar o fluxo completo da extensão ou se o gatilho dela ainda não for compatível com o pacote de emuladores do Firebase. Consulte a opção de emulador de extensões. No momento, os emuladores são compatíveis com funções acionadas por solicitação HTTP e acionadas por eventos em segundo plano para o Cloud Firestore, o Realtime Database e o Pub/Sub.

  1. Crie um novo diretório no sistema host e conecte-o ao projeto do Firebase usando firebase init.
cd ..
mkdir sample-proj
cd sample-proj
firebase init --project=projectID-or-alias
  1. Em seguida, nesse diretório, execute firebase ext:install para instalar a extensão. Substitua /path/to/extension pelo caminho absoluto do diretório que contém o arquivo extension.yaml. Isso inicia o processo de instalação da extensão e cria um arquivo .env que contém as configurações antes de enviar a configuração para o Firebase ou para os emuladores.
firebase ext:install /path/to/extension
  • Como você quer fazer a implantação diretamente no Firebase e usar o Secret Manager do Google Cloud, é necessário ativar a API Secret Manager antes de instalar a extensão.
  1. Implante no seu projeto do Firebase.
firebase deploy

Testar a extensão

  1. Depois de executar firebase deploy ou firebase emulators:start, navegue até a guia "Firestore" do console do Firebase ou da visualização da Web dos emuladores, conforme apropriado.
  2. Adiciona um documento à coleção especificada pelos campos x e y. Nesse caso, os documentos atualizados estão localizados em u/{uid} com um campo x de xv e um campo y de yv.

Tela dos emuladores do Firebase para adicionar um registro do Firestore

  1. Se você conseguir instalar a extensão, ela vai criar um novo campo chamado hash no documento depois que você salvar os dois campos.

Tela do banco de dados do Firestore de um emulador mostrando o hash adicionado

8. Parabéns!

Você converteu sua primeira função do Cloud em uma extensão do Firebase.

Você adicionou um arquivo extension.yaml e o configurou para que os desenvolvedores possam selecionar como querem que a extensão seja implantada. Em seguida, você criou uma documentação do usuário que orienta os desenvolvedores da extensão sobre o que fazer antes de configurar a extensão e quais etapas podem ser necessárias após a instalação.

Agora você conhece as principais etapas necessárias para converter uma função do Firebase em uma extensão distribuível do Firebase.

Qual é a próxima etapa?