Esta página foi traduzida pela API Cloud Translation.

Extensão de banco de dados do Google Cloud Spanner

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

Versão 2.0.0

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

Este conteúdo oferece 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 Criar e gerenciar instâncias, e um banco de dados.
Depois de criar a instância e um banco de dados, conceda permissão para acessar o banco de dados à conta de serviço do GCP que representa sua extensão. Para saber mais sobre o papel a ser usado, consulte Papéis do Cloud Spanner. Para saber mais sobre o controle de acesso do Cloud Spanner, consulte 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 ao seu banco de dados, use o Console do GCP para gerar uma chave para a conta de serviço. Use o conteúdo do arquivo JSON da chave resultante ao configurar essa extensão.
Use o conteúdo do arquivo JSON de 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 guia de 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 a ações de extensão do Cloud Spanner usando a política ExtensionCallout.

Adicionar dados

No exemplo abaixo, 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 os 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 política AssignMessage a seguir 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 este.

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

Atualizar dados

Neste exemplo, o elemento <Input> contém o username, 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 abaixo, 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
tableName	A tabela no banco de dados em que as linhas precisam 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 com o caractere @. Os valores são especificados no parâmetro params da ação.

Para saber mais 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 que é 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 de parâmetros com o símbolo @. Esses nomes de parâmetro precisam corresponder às chaves no parâmetro `params` dessa ação.	String	Nenhum.	Sim.
params	Um objeto com chaves e valores que 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 de nome e valor da 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
tableName	A tabela no banco de dados em que as linhas precisam 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 a chave primária) da linha a ser atualizada.	Matriz	Nenhum.	Sim.

Resposta

Nenhum.

Referência de configuração

Use as informações a seguir ao configurar e implantar essa extensão para uso em proxies de API. Para saber como configurar uma extensão usando o console da Apigee, consulte Adicionar e configurar uma extensão.

Propriedades de extensão comuns

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 desta extensão.

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