Estensione Google Cloud Firestore

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Versione: 2.0.2

Crea, leggi o elimina dati in un database Cloud Firestore.

Questi contenuti forniscono un riferimento per la configurazione e l'utilizzo di questa estensione. Prima di utilizzare questa estensione da un proxy API, devi:

  1. Crea un progetto Firebase nella Console Firebase in cui sono archiviati i tuoi dati.

  2. Genera una chiave per il service account.

  3. Utilizza i contenuti del file JSON della chiave risultante quando aggiungi e configuri l'estensione utilizzando il riferimento alla configurazione.

Informazioni su Cloud Firestore

Cloud Firestore archivia i dati in documenti, che vengono archiviati in raccolte. Cloud Firestore crea raccolte e documenti in modo implicito la prima volta che aggiungi dati al documento. Non è necessario creare esplicitamente raccolte o documenti.

Per saperne di più su Cloud Firestore in generale, consulta la Guida introduttiva a Firestore nella documentazione di Cloud Firestore.

Esempi

Gli esempi seguenti illustrano come configurare il supporto per le azioni di estensione di Cloud Firestore utilizzando il criterio ExtensionCallout.

Aggiungi dati

La seguente policy ExtensionCallout aggiunge un documento denominato freewill@example.com a una raccolta users. La proprietà data specifica i campi e i valori del nuovo documento.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Add-User-Data">
    <DisplayName>Add User Data</DisplayName>
    <Connector>my-cloud-firestore-extension</Connector>
    <Action>setDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "freewill@example.com",
        "data" : {
            "firstName": "Will",
            "lastName": "Witman",
            "address": "270-8243 Tempor St.",
            "city": "Fort Worth",
            "region": "TX",
            "postalCode": "86519",
            "email": "freewill@example.com",
            "username": "freewill444"
        }
    }]]></Input>
</ConnectorCallout>

Ottieni dati

In questo esempio, il criterio ExtensionCallout recupera il valore del documento freewill@example.com dalla raccolta users. In questo caso, l'attributo parsed dell'elemento <Output> è impostato su false, in modo che il risultato restituito sia JSON come stringa, anziché JSON analizzato in un oggetto. Per saperne di più, consulta il riferimento all'elemento <Output>.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Get-User-Data">
    <DisplayName>Get User Data</DisplayName>
    <Connector>straut-cloud-firestore-extension</Connector>
    <Action>getDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "freewill@example.com"
    }]]></Input>
    <Output parsed="false">firestore.userdata.retrieved</Output>
</ConnectorCallout>

Il seguente criterio Assign Message utilizza il valore della variabile che memorizza la risposta dell'estensione per assegnare il payload della risposta.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage name="CopyUserDataToResponse">
    <DisplayName>Copy User Data To Response</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{firestore.userdata.retrieved}</Payload>
    </Set>
</AssignMessage>

Elimina i dati

In questo esempio, la policy ExtensionCallout elimina il documento lizzie@example.com dalla raccolta users.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Delete-User-Data">
    <DisplayName>Delete User Data</DisplayName>
    <Connector>my-cloud-firestore-extension</Connector>
    <Action>deleteDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "lizzie@example.com"
    }]]></Input>
</ConnectorCallout>

Esegui query sui dati

In questo esempio, il criterio ExtensionCallout esegue una query su una raccolta cities. I risultati della query vengono filtrati in base ai campi state e population. In questo caso, l'attributo parsed dell'elemento <Output> è impostato su false, in modo che il risultato restituito sia JSON come stringa, anziché JSON analizzato in un oggetto. Per saperne di più, consulta il riferimento all'elemento <Output>.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Query-City-Data">
    <DisplayName>Query City Data</DisplayName>
    <Connector>cloud-firestore-extension</Connector>
    <Action>query</Action>
    <Input><![CDATA[{
        "colName":"cities",
        "queryArray":[
          ["state", "==", "CA"],
          ["population","<",1000000]
        ]
    }]]></Input>
    <Output parsed="false">compound-query-output</Output>
</ConnectorCallout>

Il seguente criterio Assign Message utilizza il valore della variabile che memorizza la risposta dell'estensione per assegnare il payload della risposta.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage name="CopyQueryResultsToResponse">
    <DisplayName>Copy Query Results To Response</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{firestore.querydata.retrieved}</Payload>
    </Set>
</AssignMessage>

Azioni

deleteDocument

Elimina un singolo documento da una raccolta.

Parametri di richiesta

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>
Parametro Descrizione Tipo Predefinito Obbligatorio
colName Nome della raccolta contenente il documento da eliminare. Stringa Nessuno. Sì.
docName Il nome del documento da eliminare. Stringa Nessuno. Sì.

Risposta

Nessuno.

getDocument

Recupera i contenuti di un singolo documento.

Parametri di richiesta

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>
Parametro Descrizione Tipo Predefinito Obbligatorio
colName Nome della raccolta da cui recuperare il documento. Stringa Nessuno. Sì.
docName Nome del documento da recuperare. Stringa Nessuno. Sì.

Risposta

Oggetto contenente i contenuti del documento in formato JSON.

query

Esegue query su una raccolta specificando le condizioni che formano un filtro.

Il parametro queryArray di questa azione specifica un array di array (o un array vuoto per nessuna condizione di filtro). Ogni array interno specifica una condizione di un filtro. Più array interni rappresentano più condizioni unite da un operatore AND.

Ogni elemento di un array di condizioni interne rappresenta una parte della condizione. Un array di condizioni ha sempre i seguenti tre elementi:

  • Un elemento a sinistra che specifica il campo della raccolta.
  • Un elemento intermedio che specifica l'operatore.
  • Un elemento a destra che specifica il valore del campo della raccolta.

L'esempio seguente specifica due array di condizioni per filtrare in base ai campi state e population della raccolta:

<Input><![CDATA[{
  "colName":"cities",
  "queryArray":[
    ["state", "==", "CA"],
    ["population","<",1000000]
  ]
}]]></Input>

In fase di runtime, questa azione viene interpretata come una query come la seguente:

Seleziona tutte le città in cui state = 'CA' e population < 1000000

Una query che include più condizioni deve essere supportata in Cloud Firestore da un indice composto. Per saperne di più, consulta Tipi di indici in Cloud Firestore.

Parametri di richiesta

Sintassi

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "queryArray" : "queryArray": query-condition-array
}]]></Input>

Esempio

In questo esempio, il parametro queryArray specifica due condizioni in base alle quali filtrare la raccolta cities specificata dal parametro colName.

Una query che include più condizioni deve essere supportata in Cloud Firestore da un indice composto. Per saperne di più, consulta Tipi di indici in Cloud Firestore.

<Input><![CDATA[{
  "colName":"cities",
  "queryArray":[["state", "==", "CA"],["population","<",1000000]]
}]]></Input>

In fase di runtime, questa azione viene interpretata come una query come la seguente:

Seleziona tutte le città in cui state = 'CA' e population < 1000000

Parametro Descrizione Tipo Predefinito Obbligatorio
colName Il nome della raccolta su cui eseguire la query. Stringa Nessuno. Sì.
queryArray Un array di array di condizioni che, insieme, specificano le parti di un filtro. Specifica un array vuoto per omettere le condizioni (non filtrare i risultati). Array Nessuno. Sì.

Risposta

Oggetto contenente i contenuti del documento in formato JSON.

setDocument

Copia un documento in una raccolta Cloud Firestore. Se il documento esiste già nella raccolta, verrà sovrascritto.

Parametri di richiesta

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name",
  "data" : "data-to-copy"
}]]></Input>
Parametro Descrizione Tipo Predefinito Obbligatorio
colName Il nome della raccolta in cui creare il documento. Stringa Nessuno. Sì.
docName Nome del documento in cui deve essere copiato data. Stringa Nessuno. Sì.
dati Dati da copiare in docName. Deve essere un oggetto JSON valido. Gli array non sono supportati. Oggetto Nessuno. No.

Risposta

Nessuno.

Riferimento alla configurazione

Utilizza quanto segue quando configuri ed esegui il deployment di questa estensione per l'utilizzo nei proxy API. Per i passaggi per configurare un'estensione utilizzando la console Apigee, vedi Aggiunta e configurazione di un'estensione.

Proprietà comuni delle estensioni

Per ogni estensione sono presenti le seguenti proprietà.

Proprietà Descrizione Predefinito Obbligatorio
name Il nome che assegni a questa configurazione dell'estensione. Nessuno Sì
packageName Nome del pacchetto dell'estensione fornito da Apigee Edge. Nessuno Sì
version Numero di versione del pacchetto dell'estensione da cui stai configurando un'estensione. Nessuno Sì
configuration Valore di configurazione specifico per l'estensione che stai aggiungendo. Vedi Proprietà per questo pacchetto di estensioni Nessuno Sì

Proprietà di questo pacchetto di estensioni

Proprietà Descrizione Predefinito Obbligatorio
firestoreDB URL del database Cloud Firestore che questa estensione deve utilizzare per effettuare le richieste. Questo URL di solito richiede il modulo https://DATABASE_NAME.firebaseio.com. Nessuno. Sì.
credenziali Se inserito nella console Apigee Edge, questo è il contenuto del file della chiave che hai generato con le istruzioni di Firebase. Se inviato utilizzando l'API di gestione, è un valore con codifica Base64 generato dal file della chiave. Nessuno. Sì.