Estensione Google Cloud Firestore

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X.
informazioni

Versione: 1.4.1

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

Questi contenuti forniscono 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 dati.

  2. Genera una chiave per l'account di servizio.

  3. Utilizza i contenuti del file JSON della chiave risultante durante l'aggiunta e la configurazione dell'estensione utilizzando il riferimento di configurazione.

Informazioni su Cloud Firestore

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

Per ulteriori informazioni su Cloud Firestore in generale, consulta la sezione Iniziare a utilizzare Firestore nella documentazione di Cloud Firestore.

Samples

I seguenti esempi mostrano come configurare il supporto per le azioni dell'estensione Cloud Firestore utilizzando il criterio ExtensionCallout.

Aggiungi dati

Le seguenti norme relative ai callout consentono di aggiungere 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>

Recupero dati

In questo esempio, i criteri ExtensionCallout recuperano 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 sugli elementi <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 Assegna messaggio 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, le norme ExtensionCallout eliminano 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>

Query sui dati

In questo esempio, le norme relative ai callout estensione eseguono la 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 sugli elementi <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 Assegna messaggio 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 richiesta

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

Risposta

Nessuna.

getDocument

Recupera i contenuti di un singolo documento.

Parametri richiesta

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

Risposta

Oggetto contenente i contenuti del documento in formato JSON.

query

Esegue una 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ù matrici interne rappresentano più condizioni unite da un operatore AND.

Ogni elemento in un array di condizioni interno rappresenta una parte della condizione. Un array di condizioni contiene sempre i tre elementi seguenti:

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

L'esempio seguente specifica due array di condizioni da 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 stato = "CA" e popolazione < 1000000

Una query che include più condizioni deve essere supportata in Cloud Firestore da un indice composto. Per ulteriori informazioni, vedi Tipi di indice in Cloud Firestore.

Parametri 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 ulteriori informazioni, vedi Tipi di indice 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 stato = "CA" e popolazione < 1000000

Parametro Descrizione Tipo Predefinito Obbligatorie
colName Nome della raccolta su cui eseguire la query. Stringa Nessuna. 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 Nessuna. 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 richiesta

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

Risposta

Nessuna.

Riferimento per la configurazione

Utilizza quanto segue durante la configurazione e il deployment di questa estensione per l'utilizzo nei proxy API. Per i passaggi per configurare un'estensione utilizzando la console Apigee, consulta Aggiungere e configurare un'estensione.

Proprietà delle estensioni comuni

Per ogni estensione sono presenti le seguenti proprietà.

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

Proprietà per questo pacchetto di estensioni

Proprietà Descrizione Predefinito Obbligatorie
firestoreDB URL del database Cloud Firestore che questa estensione deve utilizzare quando effettua le richieste. In genere questo URL ha la forma https://DATABASE_NAME.firebaseio.com. Nessuna. Sì.
credenziali Una volta inseriti nella console Apigee Edge, questi sono i contenuti del file della chiave generato con le istruzioni di Firebase. Se inviato tramite l'API di gestione, si tratta di un valore con codifica Base64 generato dal file della chiave. Nessuna. Sì.