Cette page a été traduite par l'API Cloud Translation.

Extension Google Cloud Firestore

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

Version: 2.0.0

Créer, lire ou supprimer des données dans une base de données Cloud Firestore.

Ce contenu fournit une documentation de référence pour configurer et utiliser cette extension. Avant d'utiliser cette extension à partir d'un proxy d'API, vous devez:

Créez un projet Firebase dans la console Firebase où vos données sont stockées.
Générez une clé pour le compte de service.
Utilisez le contenu du fichier JSON de clé généré lorsque vous ajoutez et configurez l'extension à l'aide de la référence de configuration.

À propos de Cloud Firestore

Cloud Firestore stocke les données dans des documents, qui sont eux-mêmes stockés dans des collections. Cloud Firestore crée implicitement les collections et les documents nécessaires la première fois qu'une donnée est ajoutée à un document. Vous n'avez pas besoin de créer explicitement des collections ni des documents.

Pour en savoir plus sur Cloud Firestore en général, consultez la section Premiers pas avec Firestore dans la documentation Cloud Firestore.

Exemples

Les exemples suivants montrent comment configurer la prise en charge des actions d'extension Cloud Firestore à l'aide de la règle ExtensionCallout.

Ajouter des données

La règle ExtensionCallout suivante ajoute un document appelé freewill@example.com à une collection users. La propriété data spécifie les champs et les valeurs du nouveau document.

<?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>

Obtenir les données

Dans cet exemple, la règle ExtensionCallout récupère la valeur du document freewill@example.com à partir de la collection users. Ici, l'attribut parsed de l'élément <Output> est défini sur false afin que le résultat renvoyé soit JSON sous forme de chaîne, plutôt que JSON analysé dans un objet. Pour en savoir plus, consultez la documentation de référence sur l'élément <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>

La règle Assign Message suivante utilise la valeur de la variable stockant la réponse de l'extension pour attribuer la charge utile de la réponse.

<?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>

Supprimer des données

Dans cet exemple, la règle ExtensionCallout supprime le document lizzie@example.com de la collection 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>

Interroger les données

Dans cet exemple, la règle ExtensionCallout interroge une collection cities. Les résultats de la requête sont filtrés par les champs state et population. Ici, l'attribut parsed de l'élément <Output> est défini sur false afin que le résultat renvoyé soit JSON sous forme de chaîne, plutôt que JSON analysé dans un objet. Pour en savoir plus, consultez la documentation de référence sur l'élément <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>

La règle Assign Message suivante utilise la valeur de la variable stockant la réponse de l'extension pour attribuer la charge utile de la réponse.

<?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>

Actions

deleteDocument

Supprime un seul document d'une collection.

Paramètres de requête

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>

Paramètre	Description	Type	Valeur par défaut	Obligatoire
colName	Nom de la collection contenant le document à supprimer.	Chaîne	Aucune.	Oui.
docName	Nom du document à supprimer.	Chaîne	Aucune.	Oui.

Réponse

Aucune.

getDocument

Récupère le contenu d'un seul document.

Paramètres de requête

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>

Paramètre	Description	Type	Valeur par défaut	Obligatoire
colName	Nom de la collection à partir de laquelle récupérer le document.	Chaîne	Aucune.	Oui.
docName	Nom du document à récupérer.	Chaîne	Aucune.	Oui.

Réponse

Objet contenant le contenu du document au format JSON.

requête

Interroge une collection en spécifiant les conditions qui constituent un filtre.

Le paramètre queryArray de cette action spécifie un tableau de tableaux (ou un tableau vide pour ne pas appliquer de conditions de filtrage). Chaque tableau interne spécifie une condition d'un filtre. Plusieurs tableaux internes représentent plusieurs conditions jointes par un opérateur AND.

Chaque élément d'un tableau de conditions internes représente une partie de la condition. Un tableau de conditions comporte toujours les trois éléments suivants:

Élément de gauche spécifiant le champ de collection.
Élément central spécifiant l'opérateur.
Élément de droite spécifiant la valeur du champ de collection.

L'exemple suivant spécifie deux tableaux de conditions à filtrer en fonction des champs state et population de la collection:

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

Au moment de l'exécution, cette action est interprétée comme une requête telle que la suivante:

Sélectionnez toutes les villes où l 'État est "CA " et la population est inférieure à 1 000 000.

Une requête incluant plusieurs conditions doit être prise en charge par un index composite dans Cloud Firestore. Pour en savoir plus, consultez la section Types d'index dans Cloud Firestore.

Paramètres de requête

Syntaxe

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

Exemple

Dans cet exemple, le paramètre queryArray spécifie deux conditions sur lesquelles filtrer la collection cities spécifiée par le paramètre colName.

Une requête incluant plusieurs conditions doit être compatible avec un index composite dans Cloud Firestore. Pour en savoir plus, consultez la section Types d'index dans Cloud Firestore.

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

Au moment de l'exécution, cette action est interprétée comme une requête telle que la suivante:

Sélectionnez toutes les villes où l 'État est "CA " et la population est inférieure à 1 000 000.

Paramètre	Description	Type	Valeur par défaut	Obligatoire
colName	Nom de la collection à interroger.	Chaîne	Aucune.	Oui.
queryArray	Tableau de tableaux de conditions qui, ensemble, spécifient les parties d'un filtre. Spécifiez un tableau vide pour ignorer les conditions (et non filtrer les résultats).	Tableau	Aucune.	Oui.

Réponse

Objet contenant le contenu du document au format JSON.

setDocument

Copier un document dans une collection Cloud Firestore Si le document existe déjà dans la collection, il est écrasé.

Paramètres de requête

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name",
  "data" : "data-to-copy"
}]]></Input>

Paramètre	Description	Type	Valeur par défaut	Obligatoire
colName	Nom de la collection dans laquelle créer le document.	Chaîne	Aucune.	Oui.
docName	Nom du document dans lequel `data` doit être copié.	Chaîne	Aucune.	Oui.
données	Données à copier dans `docName`. Il doit s'agir d'un objet JSON valide. Les tableaux ne sont pas acceptés.	Objet	Aucune.	Non.

Réponse

Aucune.

Documentation de référence sur la configuration

Utilisez les éléments suivants lorsque vous configurez et déployez cette extension pour l'utiliser dans des proxys d'API. Pour savoir comment configurer une extension à l'aide de la console Apigee, consultez Ajouter et configurer une extension.

Propriétés d'extension courantes

Les propriétés suivantes sont présentes pour chaque extension.

Propriété	Description	Par défaut	Obligatoire
`name`	Nom que vous attribuez à cette configuration de l'extension.	Aucune	Oui
`packageName`	Nom du package d'extension tel qu'indiqué par Apigee Edge.	Aucune	Oui
`version`	Numéro de version du package d'extension à partir duquel vous configurez une extension.	Aucune	Oui
`configuration`	Valeur de configuration spécifique à l'extension que vous ajoutez. Consultez Propriétés de ce package d'extension.	Aucune	Oui

Propriétés de ce package d'extension

Propriété	Description	Par défaut	Obligatoire
firestoreDB	URL de la base de données Cloud Firestore que cette extension doit utiliser lors de l'envoi de requêtes. Cette URL se présente généralement sous la forme `https://DATABASE_NAME.firebaseio.com`.	Aucune.	Oui.
credentials	Lorsque vous le saisissez dans la console Apigee Edge, il s'agit du contenu du fichier de clé que vous avez généré à l'aide des instructions Firebase. Lorsqu'il est envoyé via l'API de gestion, il s'agit d'une valeur encodée en base64 générée à partir du fichier de clés.	Aucune.	Oui.