Extensión de bases de datos de Google Cloud Spanner

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

Versión 2.0.2

Realizar operaciones de inserción, consulta y actualización en una base de datos de Cloud Spanner

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

Crea una instancia de Cloud Spanner, como se describe en Cómo crear y administrar instancias, y crea una base de datos.
Una vez que tengas la instancia y una base de datos, otorga permiso para acceder a tu base de datos a la cuenta de servicio de Google Cloud que representa tu extensión. Para obtener más información sobre el rol que se debe usar, consulta Roles de Cloud Spanner. Para obtener más información sobre el control de acceso de Cloud Spanner, consulta Cómo aplicar roles de IAM y Control de acceso para Cloud Spanner.
Cuando tengas una cuenta de servicio con permiso para el nivel de acceso a tu base de datos que desees, usa la consola de Google Cloud para generar una clave para la cuenta de servicio. Usa el contenido del archivo JSON de la clave resultante cuando configures esta extensión.
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 Spanner

Cloud Spanner es un servicio de bases de datos relacionales que resulta útil para los datos relacionales, estructurados y semiestructurados que requieren alta disponibilidad, coherencia sólida y lecturas y escrituras transaccionales.

Si recién comienzas a usar Cloud Spanner, la guía de inicio rápido en la documentación de Cloud Spanner es un buen lugar para comenzar.

Ejemplos

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

Agregar datos

En el siguiente ejemplo, la acción insert de la extensión agrega un usuario nuevo a la tabla de usuarios.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Insert-New-User">
    <DisplayName>Insert New User</DisplayName>
    <Connector>spanner-users-products</Connector>
    <Action>insert</Action>
    <Input><![CDATA[{
        "tableName" : "user",
        "rows" : [{
          "username": "jonesy42",
          "firstName": "Floyd",
          "lastName": "Jones",
          "address": "3695 Auctor Street",
          "city": "Gresham",
          "region": "OR",
          "postalCode": "12693",
          "email": "floydster@example.com"
      }]
  }]]></Input>
</ConnectorCallout>

Cómo obtener datos

En este ejemplo, una consulta recupera los valores de nombre de usuario y correo electrónico de la tabla user.

Primero, una política de AssignMessage asigna una variable postal.code.value para usarla en una cláusula WHERE de la consulta. Este es un ejemplo. Es probable que tu política establezca el valor según los parámetros de solicitud del cliente.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Postal-Code">
    <AssignTo createNew="true" transport="http" type="request"/>
    <AssignVariable>
        <Name>postal.code</Name>
        <Value>86519</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

La siguiente política ExtensionCallout ejecuta una consulta en la base de datos con el contenido de la variable postal.code.value en la cláusula WHERE.

<?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>spanner-users-products</Connector>
    <Action>querySQL</Action>
    <Input><![CDATA[{
      "sql" : "SELECT username, email FROM user WHERE postalCode = @postalCode",
      "params" : {
        "postalCode" : "{postal.code.value}"
      }
    }]]></Input>
  <Output>spanner.userdata.retrieved</Output>
</ConnectorCallout>

Luego, la siguiente política AssignMessage usa la respuesta de la extensión, almacenada en la variable spanner.userdata.retrieved, como la respuesta que se devuelve al cliente.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="Get-Query-Response-Data">
    <DisplayName>Get Query Response Data</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{spanner.userdata.retrieved}</Payload>
    </Set>
</AssignMessage>

En este ejemplo, los datos de respuesta se muestran como JSON, como se muestra a continuación.

{
  "rows": [
    {
      "username": "freewill444",
      "email": "freewill@example.com"
    }
  ]
}

Cómo actualizar datos

En este ejemplo, el elemento <Input> contiene el username (la clave principal de la tabla) y un valor nuevo para la columna email.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Update-User-Data">
    <DisplayName>Update User Data</DisplayName>
    <Connector>spanner-users-products</Connector>
    <Action>update</Action>
    <Input><![CDATA[{
        "tableName" : "user",
        "rows": [{
            "username":"Liz456",
            "email":"lizzard@example.com"
        }]
    }]]></Input>
</ConnectorCallout>

Acciones

insert

Inserta las filas especificadas en la base de datos.

Sintaxis

<Action>insert</Action>
<Input><![CDATA[{
  "tableName" : "table-to-insert-into",
  "rows" : "rows-to-insert"
}]]></Input>

Ejemplo

En el siguiente ejemplo, la acción insert de la extensión agrega un usuario nuevo a la tabla de usuarios. Se agrega una fila.

<Action>insert</Action>
<Input><![CDATA[{
    "tableName" : "user",
    "rows" : [{
      "username": "jonesy42",
      "firstName": "Floyd",
      "lastName": "Jones",
      "address": "3695 Auctor Street",
      "city": "Gresham",
      "region": "OR",
      "postalCode": "12693",
      "email": "floydster@example.com"
  }]
}]]></Input>

Parámetros de solicitud

Parámetro	Descripción	Tipo	Predeterminado	Obligatorio
nombre de la tabla	Es la tabla de la base de datos en la que se deben insertar las filas.	String	Ninguno	Sí.
filas	Son las filas que se insertarán, expresadas como un array en un objeto JSON `rows`.	Array	Ninguno	Sí.

Respuesta

Ninguno

querySQL

Consulta la base de datos con la instrucción SQL y los parámetros especificados. Los parámetros se proporcionan en la instrucción SQL con nombres antepuestos con @; los valores de los parámetros se especifican en el parámetro params de esta acción.

Para obtener detalles sobre la sintaxis de consultas de Cloud Spanner, consulta Sintaxis de consultas.

Sintaxis

<Action>querySQL</Action>
<Input><![CDATA[{
  "sql" : "sql-query-statement",
  "params" : {
    "param1" : "columnValue"
  }
}]]></Input>

Ejemplo

En este ejemplo, una consulta recupera los valores de las columnas username y email de la tabla user. La instrucción de SQL especifica un parámetro postalCode que se establece a partir de la variable de flujo postal.code.value.

<Action>querySQL</Action>
<Input><![CDATA[{
  "sql" : "SELECT username, email FROM user WHERE postalCode = @postalCode",
  "params" : {
    "postalCode" : "{postal.code.value}"
  }
}]]></Input>

Parámetros de solicitud

Parámetro	Descripción	Tipo	Predeterminado	Obligatorio
sql	Es la consulta de SQL que se ejecutará. Puedes especificar parámetros con nombres precedidos por @. Esos nombres de parámetros deben corresponder a las claves del parámetro `params` de esta acción.	String	Ninguno	Sí.
params	Es un objeto cuyas claves y valores son los nombres y valores de los parámetros que se usan en la consulta de SQL. Aquí puedes enumerar varios parámetros.	Objeto	Ninguno	Núm.

Respuesta

Es un objeto rows que contiene un array de pares nombre-valor de la columna que devolvió la consulta. Por ejemplo:

{
  "rows": [
    {
      "username": "freewill444",
      "email": "freewill@example.com"
    }
  ]
}

update

Actualiza las filas de la base de datos con los datos especificados.

Sintaxis

<Input><![CDATA[{
  "tableName" : "table-with-rows-to-update",
  "rows" : "rows-to-update"
}]]></Input>

Ejemplo

En este ejemplo, la dirección de correo electrónico del usuario cuyo username es Liz456 se actualiza con un valor nuevo. Se actualizó una fila.

<Action>update</Action>
<Input><![CDATA[{
  "tableName" : "user",
  "rows": [{
      "username":"Liz456",
      "email":"lizzard@example.com"
  }]
}]]></Input>

Parámetros de solicitud

Parámetro	Descripción	Tipo	Predeterminado	Obligatorio
nombre de la tabla	Tabla de la base de datos en la que se deben actualizar las filas.	String	Ninguno	Sí.
filas	Es un array de datos de filas que se actualizarán. Cada entidad del array debe contener el valor del ID único (como la clave principal) de la fila que se actualizará.	Array	Ninguno	Sí.

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

Especifica valores para las siguientes propiedades de configuración específicas de esta extensión.

Propiedad	Descripción	Predeterminado	Obligatorio
ID de proyecto	Es el ID del proyecto de Google Cloud que contiene la base de datos.	Ninguno	Sí.
instanceId	ID de la instancia de Cloud Spanner en tu proyecto de Google Cloud.	Ninguno	Sí.
databaseId	ID de la base de datos de Cloud Spanner.	Ninguno	Sí.
credenciales	Cuando se ingresa en la consola de Apigee Edge, este es el contenido de tu archivo de claves de la cuenta de servicio. Cuando se envía a través de la API de administración, es un valor codificado en Base64 que se genera a partir del archivo de claves de la cuenta de servicio.	Ninguno	Sí.