Extensão de banco de dados do Google Cloud Spanner

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Versão 2.0.2

Realizar operações de inserção, consulta e atualização em um banco de dados do Cloud Spanner.

Este conteúdo fornece uma referência para configurar e usar essa extensão. Antes de usar a extensão de um proxy de API usando a política ExtensionCallout, você precisa:

Crie uma instância do Cloud Spanner, conforme descrito em Como criar e gerenciar instâncias, e crie um banco de dados.
Depois de ter a instância e um banco de dados, conceda permissão para acessar o banco de dados à conta de serviço do Google Cloud que representa sua extensão. Para mais informações sobre o papel a ser usado, consulte Papéis do Cloud Spanner. Para mais informações sobre o controle de acesso do Cloud Spanner, consulte Como aplicar papéis do IAM e Controle de acesso para o Cloud Spanner.
Quando você tiver uma conta de serviço com permissão para o nível de acesso desejado ao banco de dados, use o Console do Google Cloud para gerar uma chave para a conta de serviço. Use o conteúdo do arquivo JSON de chave resultante ao configurar essa extensão.
Use o conteúdo do arquivo JSON da chave resultante ao adicionar e configurar a extensão usando a referência de configuração.

Sobre o Cloud Spanner

O Cloud Spanner é um serviço de banco de dados relacional útil para dados relacionais, estruturados e semiestruturados que exigem alta disponibilidade, consistência forte e gravações e leituras transacionais.

Se você está começando a usar o Cloud Spanner, o início rápido na documentação do Cloud Spanner é um bom lugar para começar.

Amostras

Os exemplos a seguir ilustram como configurar o suporte para ações de extensão do Cloud Spanner usando a política ExtensionCallout.

Adicionar dados

No exemplo a seguir, a ação insert da extensão adiciona um novo usuário à tabela de usuários.

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

Extrair dados

Neste exemplo, uma consulta recupera valores de nome de usuário e e-mail da tabela user.

Primeiro, uma política AssignMessage atribui uma variável postal.code.value para uso em uma cláusula WHERE de consulta. Este é um exemplo. Sua política provavelmente definiria o valor com base nos parâmetros de solicitação do 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>

A política ExtensionCallout a seguir executa uma consulta no banco de dados usando o conteúdo da variável postal.code.value na 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>

A seguinte política AssignMessage usa a resposta da extensão, armazenada na variável spanner.userdata.retrieved, como a resposta retornada ao 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>

Neste exemplo, os dados de resposta são retornados como JSON, como a seguir.

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

Atualizar dados

Neste exemplo, o elemento <Input> contém o username, que é a chave primária da tabela, e um novo valor para a coluna 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>

Ações

insert

Insere as linhas especificadas no banco de dados.

Sintaxe

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

Exemplo

No exemplo a seguir, a ação insert da extensão adiciona um novo usuário à tabela de usuários. Uma linha é adicionada.

<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 solicitação

Parâmetro	Descrição	Tipo	Padrão	Obrigatório
nome da tabela	A tabela no banco de dados em que as linhas devem ser inseridas.	String	Nenhum.	Sim.
linhas	As linhas a serem inseridas, expressas como uma matriz em um objeto JSON `rows`.	Matriz	Nenhum.	Sim.

Resposta

Nenhum.

querySQL

Consulta o banco de dados usando a instrução SQL com os parâmetros especificados. Os parâmetros são fornecidos na instrução SQL com nomes precedidos por @. Os valores de parâmetro são especificados no parâmetro params desta ação.

Para detalhes sobre a sintaxe de consulta do Cloud Spanner, consulte Sintaxe de consulta.

Sintaxe

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

Exemplo

Neste exemplo, uma consulta recupera os valores das colunas username e email da tabela user. A instrução SQL especifica um parâmetro postalCode definido pela variável de fluxo 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 solicitação

Parâmetro	Descrição	Tipo	Padrão	Obrigatório
sql	A consulta SQL a ser executada. É possível especificar parâmetros com nomes precedidos por @. Esses nomes de parâmetros precisam corresponder às chaves no parâmetro `params` dessa ação.	String	Nenhum.	Sim.
params	Um objeto cujas chaves e valores são os nomes e valores dos parâmetros usados na consulta SQL. É possível listar vários parâmetros aqui.	Objeto	Nenhum.	Não.

Resposta

Um objeto rows que contém uma matriz de pares nome-valor de coluna retornados pela consulta. Exemplo:

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

update

Atualiza linhas no banco de dados com os dados especificados.

Sintaxe

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

Exemplo

Neste exemplo, o endereço de e-mail do usuário cujo username é Liz456 é atualizado com um novo valor. Uma linha é atualizada.

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

Parâmetros de solicitação

Parâmetro	Descrição	Tipo	Padrão	Obrigatório
nome da tabela	A tabela no banco de dados em que as linhas devem ser atualizadas.	String	Nenhum.	Sim.
linhas	Uma matriz de dados de linha a serem atualizados. Cada entidade na matriz precisa conter o valor do ID exclusivo (como chave primária) da linha a ser atualizada.	Matriz	Nenhum.	Sim.

Resposta

Nenhum.

Referência de configuração

Use o seguinte ao configurar e implantar essa extensão para uso em proxies de API. Para saber como configurar uma extensão usando o console do Apigee, consulte Adicionar e configurar uma extensão.

Propriedades comuns de extensão

As propriedades a seguir estão presentes para cada extensão.

Propriedade	Descrição	Padrão	Obrigatório
`name`	Nome que será dado a esta configuração da extensão.	Nenhum	Sim
`packageName`	Nome do pacote de extensão fornecido pelo Apigee Edge.	Nenhum	Sim
`version`	Número da versão do pacote de extensão a partir do qual você está configurando uma extensão.	Nenhum	Sim
`configuration`	Valor de configuração específico da extensão que você está adicionando. Consulte Propriedades para este pacote de extensão.	Nenhum	Sim

Propriedades deste pacote de extensão

Especifique valores para as seguintes propriedades de configuração específicas dessa extensão.

Propriedade	Descrição	Padrão	Obrigatório
projectId	ID do projeto do Google Cloud que contém o banco de dados.	Nenhum.	Sim.
instanceId	ID da instância do Cloud Spanner no seu projeto do Google Cloud.	Nenhum.	Sim.
databaseId	ID do banco de dados do Cloud Spanner.	Nenhum.	Sim.
credenciais	Quando inserido no console do Apigee Edge, esse é o conteúdo do seu arquivo de chave da conta de serviço. Quando enviado usando a API Management, é um valor codificado em base64 gerado do arquivo de chave da conta de serviço.	Nenhum.	Sim.