Riutilizzare il codice di Cloud Functions come estensione Firebase

1. Prima di iniziare

Un'estensione Firebase esegue un'attività o un insieme di attività specifiche in risposta a richieste HTTP o all'attivazione di eventi da altri prodotti Firebase e Google come Firebase Cloud Messaging, Cloud Firestore o Pub/Sub.

Cosa creerai

In questo codelab, creerai un'estensione Firebase per il geohashing. Una volta dispiegato, l'estensione converte le coordinate X e Y in geohash in risposta agli eventi Firestore o tramite invocazioni di funzioni richiamabili. Questa opzione può essere utilizzata come alternativa all'implementazione della libreria GeoFire su tutte le piattaforme di destinazione per l'archiviazione dei dati, consentendoti di risparmiare tempo.

L'estensione geohash visualizzata nella Console Firebase

Cosa imparerai a fare

  • Come trasformare il codice Cloud Functions esistente in un'estensione Firebase distribuibile
  • Come configurare un file extension.yaml
  • Come memorizzare stringhe sensibili (chiavi API) in un'estensione
  • Come consentire agli sviluppatori dell'estensione di configurarla in base alle loro esigenze
  • Come testare e implementare l'estensione

Che cosa ti serve

2. Configurazione

Ottieni il codice

Tutto ciò che ti serve per questa estensione si trova in un repository GitHub. Per iniziare, prendi il codice e aprilo nel tuo ambiente di sviluppo preferito.

  1. Estrai il file ZIP scaricato.
  2. Per installare le dipendenze richieste, apri il terminale nella directory functions ed esegui il comando npm install.

Configura Firebase

Questo codelab consiglia vivamente di utilizzare gli emulatori Firebase. Se vuoi provare lo sviluppo di estensioni con un progetto Firebase reale, consulta la sezione Creare un progetto Firebase. Questo codelab utilizza Cloud Functions, quindi se utilizzi un progetto Firebase reale anziché gli emulatori, devi eseguire l'upgrade al piano tariffario Blaze.

Vuoi andare avanti?

Puoi scaricare una versione completa del codelab. Se non riesci a procedere o se vuoi vedere come appare un'estensione completata, dai un'occhiata al ramo codelab-end del repository GitHub o scarica il file ZIP completo.

3. Esamina il codice

  • Apri il file index.ts dal file ZIP. Tieni presente che contiene due dichiarazioni di Cloud Functions.

A cosa servono queste funzioni?

Queste funzioni di demo vengono utilizzate per il geohashing. Prendono una coppia di coordinate e la trasformano in un formato ottimizzato per le query geografiche in Firestore. Le funzioni simulano l'utilizzo di una chiamata API in modo da poter scoprire di più sulla gestione dei tipi di dati sensibili nelle estensioni. Per ulteriori informazioni, consulta la documentazione su come eseguire query geografiche sui dati in Firestore.

Costanti di funzione

Le costanti vengono dichiarate all'inizio, nella parte superiore del file index.ts. Ad alcune di queste costanti viene fatto riferimento negli attivatori definiti dell'estensione.

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);

Trigger di Firestore

La prima funzione nel file index.ts ha il seguente aspetto:

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,
        }
      );
  });

Questa funzione è un attivatore Firestore. Quando si verifica un evento di scrittura nel database, la funzione reagisce cercando un campo xv e un campo yv e, se entrambi i campi esistono, calcola il geohash e scrive l'output in una posizione di output del documento specificata. Il documento di input è definito dalla costante users/{uid}, il che significa che la funzione legge ogni documento scritto nella raccolta users/ ed elabora un geohash per questi documenti. L'hash viene poi visualizzato in un campo hash nello stesso documento.

Funzioni chiamabili

La funzione successiva nel file index.ts ha il seguente aspetto:

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};
});

Tieni presente la funzione onCall. Indica che questa funzione è una funzione richiamabile, che può essere chiamata dal codice dell'applicazione client. Questa funzione richiamabile accetta i parametri x e y e restituisce un geohash. Sebbene questa funzione non venga chiamata direttamente in questo codelab, è inclusa come esempio di elemento da configurare nell'estensione Firebase.

4. Configurare un file extension.yaml

Ora che sai cosa fa il codice di Cloud Functions nella tua estensione, puoi impacchettarlo per la distribuzione. Ogni estensione Firebase è dotata di un file extension.yaml che descrive cosa fa e come si comporta.

Un file extension.yaml richiede alcuni metadati iniziali relativi all'estensione. Ogni passaggio seguente ti aiuta a capire il significato di tutti i campi e perché ti servono.

  1. Crea un file extension.yaml nella directory principale del progetto che hai scaricato in precedenza. Inizia aggiungendo quanto segue:
name: geohash-ext
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version (do not edit)

Il nome dell'estensione viene utilizzato come base dell'ID istanza dell'estensione (gli utenti possono installare più istanze di un'estensione, ciascuna con un proprio ID). Firebase genera quindi il nome degli account di servizio dell'estensione e delle risorse specifiche dell'estensione utilizzando l'ID istanza. Il numero di versione indica la versione dell'estensione. Deve seguire il versionamento semantico e devi aggiornarlo ogni volta che apporti modifiche alla funzionalità dell'estensione. La versione della specifica dell'estensione viene utilizzata per determinare quale specifica delle estensioni Firebase seguire. In questo caso, viene utilizzata v1beta.

  1. Aggiungi alcuni dettagli facili da usare al file YAML:
...

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

Il nome visualizzato è una rappresentazione facile da ricordare del nome dell'estensione quando gli sviluppatori interagiscono con l'estensione. La descrizione fornisce una breve panoramica della funzionalità dell'estensione. Quando l'estensione viene implementata su extensions.dev, ha il seguente aspetto:

Estensione Geohash Converter come mostrato su extensions.dev

  1. Specifica la licenza per il codice nell'estensione.
...

license: Apache-2.0  # The license you want for the extension
  1. Indica chi ha scritto l'estensione e se è necessaria o meno la fatturazione per installarla:
...

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

billingRequired: true

La sezione author viene utilizzata per comunicare agli utenti chi contattare in caso di problemi con l'estensione o se vogliono saperne di più. billingRequired è un parametro obbligatorio e deve essere impostato su true poiché tutte le estensioni si basano su Cloud Functions, che richiede il piano Blaze.

Questo riguarda il numero minimo di campi richiesti nel file extension.yaml per identificare questa estensione. Per ulteriori dettagli su altre informazioni di identificazione che puoi specificare in un'estensione, consulta la documentazione.

5. Converti il codice di Cloud Functions in una risorsa Estensioni

Una risorsa di estensione è un elemento creato da Firebase nel progetto durante l'installazione di un'estensione. L'estensione è quindi proprietaria di queste risorse e dispone di un account di servizio specifico che le gestisce. In questo progetto, queste risorse sono Cloud Functions, che devono essere definite nel file extension.yaml perché l'estensione non crea automaticamente le risorse dal codice nella cartella delle funzioni. Se le Funzioni Cloud non sono dichiarate esplicitamente come risorsa, non possono essere implementate durante il deployment dell'estensione.

Posizione di deployment definita dall'utente

  1. Consenti all'utente di specificare la posizione in cui vuole implementare questa estensione e di decidere se è meglio ospitarla più vicino agli utenti finali o al database. Nel file extension.yaml, includi l'opzione per scegliere una località.

extension.yaml

Ora è tutto pronto per scrivere la configurazione della risorsa funzione.

  1. Nel file extension.yaml, crea un oggetto risorsa per la funzione locationUpdate. Aggiungi quanto segue al file 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}

name viene definito come il nome della funzione definito nel file index.ts del progetto. Specifica il type della funzione di cui viene eseguito il deployment, che per il momento dovrebbe essere sempre firebaseextensions.v1beta.function. Poi, definisci il properties di questa funzione. La prima proprietà che definisci è il eventTrigger associato a questa funzione. Per rispecchiare ciò che l'estensione supporta attualmente, utilizza il eventType di providers/cloud.firestore/eventTypes/document.write, che si trova nella documentazione Scrivere funzioni Cloud per l'estensione. resource viene definito come la posizione dei documenti. Poiché il tuo obiettivo attuale è rispecchiare ciò che esiste nel codice, il percorso del documento ascolta users/{uid}, preceduto dalla posizione predefinita del database.

  1. L'estensione ha bisogno delle autorizzazioni di lettura e scrittura per il database Firestore. Alla fine del file extension.yaml, specifica i ruoli IAM a cui l'estensione deve avere accesso per lavorare con il database nel progetto Firebase dello sviluppatore.
roles:
  - role: datastore.user
    reason: Allows the extension to read / write to your Firestore instance.

Il ruolo datastore.user proviene dall'elenco dei ruoli IAM supportati per le estensioni. Poiché l'estensione leggerà e scriverà, il ruolo datastore.user è adatto a questo caso.

  1. Deve essere aggiunta anche la funzione richiamabile. Nel file extension.yaml, crea una nuova risorsa nella proprietà resources. Queste proprietà sono specifiche per una funzione richiamabile:
  - name: callableHash
    type: firebaseextensions.v1beta.function
    properties:
      httpsTrigger: {}

Sebbene la risorsa precedente utilizzasse un eventTrigger, qui utilizzi un httpsTrigger, che copre sia le funzioni richiamabili sia le funzioni HTTPS.

Controllo codice

È stata necessaria molta configurazione per fare in modo che extension.yaml corrisponda a tutto ciò che viene eseguito dal codice nel file index.ts. A questo punto, il file extension.yaml completato dovrebbe avere il seguente aspetto:

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.

Controllo dello stato

A questo punto, hai configurato i componenti funzionali iniziali dell'estensione, quindi puoi provarla utilizzando gli emulatori Firebase.

  1. Se non l'hai già fatto, chiama npm run build nella cartella delle funzioni del progetto di estensioni scaricato.
  2. Crea una nuova directory sul sistema host e collegala al tuo progetto Firebase utilizzando 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. Dalla stessa directory, esegui firebase ext:install. Sostituisci /path/to/extension con il percorso assoluto della directory contenente il file extension.yaml.
firebase ext:install /path/to/extension

    This command does two things:
  • Ti chiede di specificare la configurazione per l'istanza dell'estensione e crea un file *.env contenente le informazioni di configurazione per l'istanza.
  • L'istanza dell'estensione viene aggiunta alla sezione extensions di firebase.json. Questa operazione funge da mappa dell'ID istanza alla versione dell'estensione.
  • Poiché esegui il deployment del progetto localmente, puoi specificare di voler utilizzare un file locale anziché Secret Manager di Google Cloud.

Screenshot della procedura di installazione dell'estensione che mostra che il file locale viene utilizzato per i secret durante l'installazione di questa estensione

  1. Avvia gli emulatori Firebase con la nuova configurazione:
firebase emulators:start
  1. Dopo aver eseguito emulators:start, vai alla scheda Firestore nella visualizzazione web degli emulatori.
  2. Aggiungi un documento alla raccolta users con un campo numerico xv e un campo numerico yv.

Una finestra di dialogo visualizzata negli emulatori Firebase per avviare una raccolta con l'ID raccolta contenente la frase

  1. Se l'installazione dell'estensione è andata a buon fine, nel documento viene creato un nuovo campo denominato hash.

La raccolta utenti con un documento utente contenente un campo xv, yv e hash.

Eseguire la pulizia per evitare conflitti

  • Al termine del test, disinstalla l'estensione: aggiornerai il codice dell'estensione e non vuoi che entri in conflitto con l'estensione corrente in un secondo momento.

Le estensioni consentono di installare contemporaneamente più versioni della stessa estensione, quindi la disinstallazione ti assicura che non ci siano conflitti con un'estensione installata in precedenza.

firebase ext:uninstall geohash-ext

La soluzione attuale funziona, ma, come accennato all'inizio del progetto, è presente una chiave API hardcoded per simulare la comunicazione con un servizio. Come faccio a utilizzare la chiave API dell'utente finale anziché quella fornita inizialmente? Continua a leggere per scoprirlo.

6. Rendere l'utente dell'estensione configurabile

A questo punto del codelab, hai un'estensione configurata per l'utilizzo con la configurazione opinata delle funzioni che hai già scritto, ma cosa succede se l'utente vuole utilizzare latitudine e longitudine anziché y e x per i campi che indicano la posizione su un piano cartesiano? Inoltre, come puoi chiedere all'utente finale di fornire la propria chiave API anziché consentirgli di utilizzare quella fornita? Potresti superare rapidamente la quota per l'API. In questo caso, configuri e utilizzi i parametri.

Definisci i parametri di base nel file extension.yaml

Inizia convertendo gli elementi per i quali gli sviluppatori potrebbero avere una configurazione personalizzata. Il primo è costituito dai parametri XFIELD e YFIELD.

  1. Nel file extension.yaml, aggiungi il seguente codice, che utilizza i parametri di campo XFIELD e YFIELD. Questi parametri si trovano all'interno della proprietà YAML params definita in precedenza:

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 nomina il parametro in modo che sia visibile a te, il produttore dell'estensione. Utilizza questo valore in un secondo momento quando specifichi i valori dei parametri.
  • label è un identificatore leggibile che consente allo sviluppatore di sapere cosa fa il parametro.
  • description fornisce una descrizione dettagliata del valore. Poiché supporta Markdown, può includere link a documentazione aggiuntiva o evidenziare parole che potrebbero essere importanti per lo sviluppatore.
  • type definisce il meccanismo di inserimento per la modalità di impostazione del valore del parametro da parte dell'utente. Esistono molti tipi, tra cui string, select, multiSelect, selectResource e secret. Per scoprire di più su ciascuna di queste opzioni, consulta la documentazione.
  • validationRegex vincola l'inserimento dello sviluppatore a un determinato valore regex (nell'esempio si basa sulle linee guida per i nomi di campo semplici trovate qui); se non riesce...
  • validationErrorMessage avvisa lo sviluppatore del valore dell'errore.
  • default è il valore che verrebbe utilizzato se lo sviluppatore non inserisse alcun testo.
  • required indica che lo sviluppatore non è tenuto a inserire alcun testo.
  • immutable consente allo sviluppatore di aggiornare questa estensione e modificare questo valore. In questo caso, lo sviluppatore dovrebbe essere in grado di modificare i nomi dei campi in base alle modifiche dei requisiti.
  • example fornisce un'idea di come potrebbe essere un input valido.

È stato difficile da capire.

  1. Devi aggiungere altri tre parametri al file extension.yaml prima di aggiungere un parametro speciale.
  - 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

Definire i parametri sensibili

Ora devi gestire la chiave API specificata dall'utente. Si tratta di una stringa sensibile che non deve essere archiviata in testo normale nella funzione. Archivia questo valore in Secret Manager di Cloud. Si tratta di una posizione speciale nel cloud che memorizza i secret criptati e ne impedisce la fuga accidentale. Lo sviluppatore deve pagare per l'utilizzo di questo servizio, ma aggiunge un ulteriore livello di sicurezza alle chiavi API e potenzialmente limita le attività fraudolente. La documentazione per l'utente avvisa lo sviluppatore che si tratta di un servizio a pagamento, in modo che non ci siano sorprese in fatturazione. Nel complesso, l'utilizzo è simile a quello delle altre risorse stringa sopra menzionate. L'unica differenza è il tipo, chiamato secret.

  • Nel file extension.yaml, aggiungi il seguente codice:

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

Aggiorna gli attributi resource per utilizzare i parametri

Come accennato in precedenza, la risorsa (non la funzione) definisce il modo in cui viene osservata, pertanto la risorsa locationUpdate deve essere aggiornata per utilizzare il nuovo parametro.

  • Nel file extension.yaml, aggiungi il seguente codice:

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}

Controlla il file extension.yaml

  • Esamina il file extension.yaml. Il sito dovrebbe avere il seguente aspetto:

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.

Accedere ai parametri nel codice

Ora che tutti i parametri sono configurati nel file extension.yaml, aggiungili al file index.ts.

  • Nel file index.ts, sostituisci i valori predefiniti con process.env.PARAMETER_NAME, che recupera i valori dei parametri appropriati e li inserisce nel codice della funzione di cui è stato eseguito il deployment nel progetto Firebase dello sviluppatore.

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!;

In genere, è consigliabile eseguire controlli di nullità con i valori delle variabili di ambiente, ma in questo caso puoi assumere che i valori dei parametri siano copiati correttamente. Il codice è ora configurato per funzionare con i parametri dell'estensione.

7. Creare la documentazione per gli utenti

Prima di testare il codice su emulatori o nel marketplace di estensioni Firebase, l'estensione deve essere documentata in modo che gli sviluppatori sappiano cosa ottengono quando la utilizzano.

  1. Per iniziare, crea il file PREINSTALL.md, che viene utilizzato per descrivere la funzionalità, eventuali prerequisiti per l'installazione e le potenziali implicazioni per la fatturazione.

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. Per risparmiare tempo nella scrittura del file README.md per questo progetto, utilizza il metodo di praticità:
firebase ext:info . --markdown > README.md

In questo modo vengono combinati i contenuti del file PREINSTALL.md e ulteriori dettagli sull'estensione dal file extension.yaml.

Infine, informa lo sviluppatore dell'estensione su alcuni dettagli aggiuntivi relativi all'estensione appena installata. Lo sviluppatore potrebbe ricevere alcune istruzioni e informazioni aggiuntive dopo aver completato l'installazione e alcune attività dettagliate di post-installazione, come la configurazione del codice client, qui.

  1. Crea un file POSTINSTALL.md e includi le seguenti informazioni di post-installazione:

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);
  });

Monitoraggio

Come best practice, puoi monitorare l'attività dell'estensione installata, inclusi i controlli relativi a integrità, utilizzo e log.

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

In questo modo, le funzioni vengono ricompilate in modo che il codice sorgente più recente sia pronto per il deployment insieme all'estensione quando viene eseguito su un emulatore o direttamente su Firebase.

A questo punto, crea una nuova directory da cui testare l'estensione. Poiché l'estensione è stata sviluppata a partire da funzioni esistenti, non eseguire il test dalla cartella in cui è stata configurata, in quanto vengono tentate di implementare anche le funzioni e le regole Firebase.

Installa e testa con gli emulatori Firebase

  1. Crea una nuova directory sul sistema host e collegala al tuo progetto Firebase utilizzando firebase init.
mkdir sample-proj
cd sample-proj
firebase init --project=projectID-or-alias
  1. Da questa directory, esegui firebase ext:install per installare l'estensione. Sostituisci /path/to/extension con il percorso assoluto della directory contenente il file extension.yaml. Viene avviata la procedura di installazione dell'estensione e viene creato un file .env contenente le configurazioni prima di inviarle a Firebase o agli emulatori.
firebase ext:install /path/to/extension
  • Poiché stai eseguendo il deployment del progetto localmente, specifica che vuoi utilizzare un file locale anziché Secret Manager di Google Cloud.

da928c65ffa8ce15.png

  1. Avvia la suite di emulatori locale:
firebase emulators:start

Installa e testa con un progetto Firebase reale

Puoi installare l'estensione in un progetto Firebase reale. Ti consigliamo di utilizzare un progetto di test per i test. Utilizza questo flusso di lavoro di test se vuoi testare il flusso end-to-end dell'estensione o se l'attivatore dell'estensione non è ancora supportato dalla suite di emulatori Firebase (vedi l'opzione Emulatore di estensioni). Al momento gli emulatori supportano le funzioni attivate da richieste HTTP e le funzioni in background attivate da eventi per Cloud Firestore, Realtime Database e Pub/Sub.

  1. Crea una nuova directory sul sistema host e collegala al tuo progetto Firebase utilizzando firebase init.
cd ..
mkdir sample-proj
cd sample-proj
firebase init --project=projectID-or-alias
  1. Quindi, da quella directory, esegui firebase ext:install per installare l'estensione. Sostituisci /path/to/extension con il percorso assoluto della directory contenente il file extension.yaml. Viene avviata la procedura di installazione dell'estensione e viene creato un file .env contenente le configurazioni prima di inviarle a Firebase o agli emulatori.
firebase ext:install /path/to/extension
  • Poiché vuoi eseguire il deployment direttamente in Firebase e vuoi utilizzare Secret Manager di Google Cloud, devi attivare l'API Secret Manager prima di installare l'estensione.
  1. Esegui il deployment nel progetto Firebase.
firebase deploy

Testare l'estensione

  1. Dopo aver eseguito firebase deploy o firebase emulators:start, vai alla scheda Firestore della Console Firebase o alla visualizzazione web degli emulatori, a seconda dei casi.
  2. Aggiungi un documento alla raccolta specificata dai campi x e y. In questo caso, i documenti aggiornati si trovano in u/{uid} con un campo x di xv e un campo y di yv.

Schermata di Firebase Emulators per aggiungere un record Firestore

  1. Se l'installazione dell'estensione è andata a buon fine, l'estensione crea un nuovo campo denominato hash nel documento dopo aver salvato i due campi.

Schermata del database Firestore di un emulatore che mostra l&#39;hash aggiunto

8. Complimenti!

Hai convertito correttamente la tua prima funzione Cloud in un'estensione Firebase.

Hai aggiunto un file extension.yaml e lo hai configurato in modo che gli sviluppatori possano selezionare la modalità di implementazione dell'estensione. Hai poi creato la documentazione utente che fornisce indicazioni su cosa devono fare gli sviluppatori dell'estensione prima di configurarla e su quali passaggi potrebbero dover eseguire dopo averla installata correttamente.

Ora conosci i passaggi chiave necessari per convertire una funzione Firebase in un'estensione Firebase distribuibile.

Passaggi successivi