Extensión de bases de datos de Google Cloud Spanner

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Versión 1.4.1

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

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

  1. Crea una instancia de Cloud Spanner como se describe en Cómo crear y administrar instancias y crea una base de datos.

  2. 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 GCP que representa tu extensión. Para obtener más información sobre el rol que debes usar, consulta Roles de Cloud Spanner. Para obtener más información sobre el control de acceso de Cloud Spanner, consulta Aplica roles de IAM y Control de acceso para Cloud Spanner.

  3. Cuando tengas una cuenta de servicio con permiso para el nivel de acceso a la base de datos que deseas, usa GCP Console a fin de generar una clave para la cuenta de servicio. Usa el contenido del archivo JSON de claves resultante cuando configures esta extensión.

  4. Usa el contenido del archivo JSON de claves resultante cuando agregues y configures la extensión mediante la referencia de configuración.

Acerca de Cloud Spanner

Cloud Spanner es un servicio de bases de datos relacionales útil para 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 de la documentación de Cloud Spanner es un buen punto de partida.

Ejemplos

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

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 deAssignMessage asigna una variable de postal.code.value para usar en una cláusula WHERE de consulta. Este es un ejemplo. Es probable que tu política establezca el valor en función de 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 ExtensionExtension 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 deAssignMessage usa la respuesta de la extensión, almacenada en la variable spanner.userdata.retrieved, como la respuesta que se muestra 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, de la siguiente manera.

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

Cómo actualizar datos

En este ejemplo, el elemento <Input> contiene username, la clave primaria 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 Predeterminada Obligatorias
tableName La tabla de la base de datos en la que se deben insertar las filas. Cadena Ningún contenido de este tipo Sí.
filas Las filas que se insertarán expresadas como un array en un objeto rows de JSON. Array Ningún contenido de este tipo Sí.

Respuesta

Ningún contenido de este tipo

querySQL

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

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

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 Predeterminada Obligatorias
sql La consulta SQL que se ejecutará. Puedes especificar parámetros con nombres de parámetros precedidos por @. Esos nombres de parámetros deben corresponder a las claves en el parámetro params de esta acción. Cadena Ningún contenido de este tipo Sí.
params Es un objeto cuyas claves y valores son los nombres y valores de los parámetros utilizados en la consulta en SQL. Puedes enumerar varios parámetros aquí. Objeto Ningún contenido de este tipo No.

Respuesta

Un objeto rows que contiene un array de pares de nombre-valor de columna que muestra 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, se actualiza la dirección de correo electrónico del usuario cuyo username es Liz456 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 Predeterminada Obligatorias
tableName La tabla de la base de datos en la que se deben actualizar las filas. Cadena Ningún contenido de este tipo Sí.
filas Un array de datos de filas para actualizar. Cada entidad del array debe contener el valor de ID único (como la clave primaria) para la fila que se actualizará. Array Ningún contenido de este tipo Sí.

Respuesta

Ningún contenido de este tipo

Referencia de configuración

Usa la siguiente información cuando configures e implementes esta extensión para usarla en proxies de API. Si quieres conocer los pasos para configurar una extensión con la consola de Apigee, consulta Agrega y configura 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
packageName Nombre del paquete de extensiones proporcionado por Apigee Edge. Ninguna
version El número de versión del paquete de extensiones desde el que quieres configurar la extensión. Ninguna
configuration Es un valor de configuración específico para la extensión que agregas. Consulta Propiedades para este paquete de extensiones Ninguna

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 Predeterminada Obligatorias
projectId ID del proyecto de GCP que contiene la base de datos. Ningún contenido de este tipo Sí.
instanceId ID de la instancia de Cloud Spanner en tu proyecto de GCP. Ningún contenido de este tipo Sí.
databaseId ID de la base de datos de Cloud Spanner. Ningún contenido de este tipo 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 Management, es un valor codificado en base64 que se genera a partir del archivo de claves de la cuenta de servicio. Ningún contenido de este tipo Sí.