Extensión de Google Cloud Firestore

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

Versión: 2.0.2

Crear, leer o borrar datos en una base de datos de Cloud Firestore

En este contenido, se proporciona información de referencia para configurar y usar esta extensión. Antes de usar esta extensión desde un proxy de API, debes hacer lo siguiente:

Crea un proyecto de Firebase en Firebase console donde se almacenarán tus datos.
Genera una clave para la cuenta de servicio.
Usa el contenido del archivo JSON de la clave resultante cuando agregues y configures la extensión con la referencia de configuración.

Acerca de Cloud Firestore

Cloud Firestore almacena datos en documentos, que se almacenan en colecciones. Cloud Firestore crea colecciones y documentos de forma implícita la primera vez que agregas datos al documento. No es necesario que crees colecciones o documentos de forma explícita.

Para obtener más información sobre Cloud Firestore en general, consulta Primeros pasos con Firestore en la documentación de Cloud Firestore.

Ejemplos

En los siguientes ejemplos, se ilustra cómo configurar la compatibilidad con las acciones de la extensión de Cloud Firestore con la política ExtensionCallout.

Agregar datos

La siguiente política de ExtensionCallout agrega un documento llamado freewill@example.com a una colección users. La propiedad data especifica los campos y los valores del documento nuevo.

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

Cómo obtener datos

En este ejemplo, la política ExtensionCallout recupera el valor del documento freewill@example.com de la colección users. Aquí, el atributo parsed del elemento <Output> se establece en false para que el resultado devuelto sea JSON como una cadena, en lugar de JSON analizado en un objeto. Para obtener más información, consulta la referencia del 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>

La siguiente política de Assign Message usa el valor de la variable que almacena la respuesta de la extensión para asignar la carga útil de la respuesta.

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

Borra datos

En este ejemplo, la política de ExtensionCallout borra el documento lizzie@example.com de la colección 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>

Consulta datos

En este ejemplo, la política ExtensionCallout consulta una colección de cities. Los resultados de la búsqueda se filtran según los campos state y population. Aquí, el atributo parsed del elemento <Output> se establece en false para que el resultado devuelto sea JSON como una cadena, en lugar de JSON analizado en un objeto. Para obtener más información, consulta la referencia del 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>

La siguiente política de Assign Message usa el valor de la variable que almacena la respuesta de la extensión para asignar la carga útil de la respuesta.

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

Acciones

deleteDocument

Borra un solo documento de una colección.

Parámetros de solicitud

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

Parámetro	Descripción	Tipo	Predeterminado	Obligatorio
colName	Nombre de la colección que contiene el documento que se borrará.	String	Ninguno	Sí.
docName	Nombre del documento que se borrará.	String	Ninguno	Sí.

Respuesta

Ninguno

getDocument

Recupera el contenido de un solo documento.

Parámetros de solicitud

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

Parámetro	Descripción	Tipo	Predeterminado	Obligatorio
colName	Nombre de la colección de la que se recuperará el documento.	String	Ninguno	Sí.
docName	Nombre del documento que se recuperará.	String	Ninguno	Sí.

Respuesta

Objeto que contiene el contenido del documento en formato JSON.

consulta

Consulta una colección especificando las condiciones que forman un filtro.

El parámetro queryArray de esta acción especifica un array de arrays (o un array vacío si no hay condiciones de filtrado). Cada array interno especifica una condición de un filtro. Varios arreglos internos representan varias condiciones unidas por un operador Y.

Cada elemento de un array de condiciones internas representa una parte de la condición. Un array de condiciones siempre tiene los siguientes tres elementos:

Es un elemento a la izquierda que especifica el campo de la colección.
Un elemento intermedio que especifica el operador.
Es un elemento a la derecha que especifica el valor del campo de la colección.

En el siguiente ejemplo, se especifican dos arrays de condiciones para filtrar según los campos state y population de la colección:

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

En el tiempo de ejecución, esta acción se interpreta como una búsqueda, como la siguiente:

Selecciona todas las ciudades en las que state = "CA" y population < 1000000.

Cloud Firestore debe admitir una consulta que incluya varias condiciones con un índice compuesto. Para obtener más información, consulta Tipos de índices en Cloud Firestore.

Parámetros de solicitud

Sintaxis

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

Ejemplo

En este ejemplo, el parámetro queryArray especifica dos condiciones para filtrar la colección cities especificada por el parámetro colName.

Cloud Firestore debe admitir con un índice compuesto una consulta que incluya varias condiciones. Para obtener más información, consulta Tipos de índices en Cloud Firestore.

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

En el tiempo de ejecución, esta acción se interpreta como una búsqueda, como la siguiente:

Selecciona todas las ciudades en las que state = "CA" y population < 1000000.

Parámetro	Descripción	Tipo	Predeterminado	Obligatorio
colName	Nombre de la colección que se consultará.	String	Ninguno	Sí.
queryArray	Es un array de arrays de condiciones que, en conjunto, especifican las partes de un filtro. Especifica un array vacío para omitir condiciones (no filtrar resultados).	Array	Ninguno	Sí.

Respuesta

Objeto que contiene el contenido del documento en formato JSON.

setDocument

Copia un documento en una colección de Cloud Firestore. Si el documento ya existe en la colección, se sobrescribe.

Parámetros de solicitud

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

Parámetro	Descripción	Tipo	Predeterminado	Obligatorio
colName	Nombre de la colección en la que se creará el documento.	String	Ninguno	Sí.
docName	Nombre del documento en el que se debe copiar `data`.	String	Ninguno	Sí.
datos	Datos que se copiarán en `docName`. Debe ser un objeto JSON válido. No se admiten los arrays.	Objeto	Ninguno	Núm.

Respuesta

Ninguno

Referencia de configuración

Usa la siguiente información cuando configures e implementes esta extensión para usarla en proxies de API. Si deseas conocer los pasos para configurar una extensión con la consola de Apigee, consulta Cómo agregar y configurar una extensión.

Propiedades comunes de las extensiones

Las siguientes propiedades están presentes para cada extensión.

Propiedad	Descripción	Predeterminado	Obligatorio
`name`	Nombre que asignas a esta configuración de la extensión.	Ninguna	Sí
`packageName`	Nombre del paquete de extensiones proporcionado por Apigee Edge.	Ninguna	Sí
`version`	El número de versión del paquete de extensiones desde el que quieres configurar la extensión.	Ninguna	Sí
`configuration`	Es un valor de configuración específico para la extensión que agregas. Consulta Propiedades para este paquete de extensiones	Ninguna	Sí

Propiedades de este paquete de extensión

Propiedad	Descripción	Predeterminado	Obligatorio
firestoreDB	Es la URL de la base de datos de Cloud Firestore que esta extensión debe usar cuando realice solicitudes. Por lo general, esta URL tiene el formato `https://DATABASE_NAME.firebaseio.com`.	Ninguno	Sí.
credenciales	Cuando se ingresa en la consola de Apigee Edge, este es el contenido del archivo de clave que generaste con las instrucciones de Firebase. Cuando se envía con la API de administración, es un valor codificado en base64 que se genera a partir del archivo de clave.	Ninguno	Sí.