Estensione database Google Cloud Spanner

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Versione 2.0.2

Esegui operazioni di inserimento, query e aggiornamento su un database Cloud Spanner.

Questi contenuti forniscono un riferimento per la configurazione e l'utilizzo di questa estensione. Prima di utilizzare l'estensione da un proxy API utilizzando il criterio ExtensionCallout, devi:

Crea un'istanza Cloud Spanner, come descritto in Creazione e gestione delle istanze, e crea un database.
Una volta che hai l'istanza e un database, concedi l'autorizzazione per accedere al database al service account Google Cloud che rappresenta la tua estensione. Per saperne di più sul ruolo da utilizzare, consulta Ruoli Cloud Spanner. Per saperne di più sul controllo dell'accesso di Cloud Spanner, consulta Applicazione dei ruoli IAM e Controllo dell'accesso per Cloud Spanner.
Quando hai un account di servizio con l'autorizzazione per il livello di accesso al database che ti interessa, utilizza la console Google Cloud per generare una chiave per l'account di servizio. Utilizza i contenuti del file JSON della chiave risultante quando configuri questa estensione.
Utilizza i contenuti del file JSON della chiave risultante quando aggiungi e configuri l'estensione utilizzando il riferimento alla configurazione.

Informazioni su Cloud Spanner

Cloud Spanner è un servizio di database relazionale utile per dati relazionali, strutturati e semistrutturati che richiedono alta disponibilità, elevata coerenza e letture e scritture transazionali.

Se hai appena iniziato a utilizzare Cloud Spanner, la guida rapida nella documentazione di Cloud Spanner è un buon punto di partenza.

Esempi

Gli esempi seguenti illustrano come configurare il supporto per le azioni di estensione di Cloud Spanner utilizzando il ExtensionCallout policy.

Aggiungi dati

Nell'esempio seguente, l'azione insert dell'estensione aggiunge un nuovo utente alla tabella degli utenti.

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

Ottieni dati

In questo esempio, una query recupera i valori di nome utente ed email dalla tabella user.

Innanzitutto, un criterio AssignMessage assegna una variabile postal.code.value da utilizzare in una clausola WHERE di una query. Questo è un esempio. Probabilmente la tua policy imposterà il valore in base ai parametri di richiesta del client.

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

Il seguente criterio ExtensionCallout esegue una query sul database utilizzando i contenuti della variabile postal.code.value nella clausola 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>

Il seguente criterio AssignMessage utilizza quindi la risposta dell'estensione, memorizzata nella variabile spanner.userdata.retrieved, come risposta restituita al client.

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

In questo esempio, i dati della risposta vengono restituiti in formato JSON, come segue.

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

Aggiorna dati

In questo esempio, l'elemento <Input> contiene username, la chiave primaria della tabella, e un nuovo valore per la colonna 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>

Azioni

insert

Inserisce le righe specificate nel database.

Sintassi

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

Esempio

Nell'esempio seguente, l'azione insert dell'estensione aggiunge un nuovo utente alla tabella degli utenti. Viene aggiunta una riga.

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

Parametri di richiesta

Parametro	Descrizione	Tipo	Predefinito	Obbligatorio
nome tabella	La tabella del database in cui devono essere inserite le righe.	Stringa	Nessuno.	Sì.
righe	Le righe da inserire espresse come array in un oggetto JSON `rows`.	Array	Nessuno.	Sì.

Risposta

Nessuno.

querySQL

Esegue query sul database utilizzando l'istruzione SQL con i parametri specificati. I parametri vengono forniti nell'istruzione SQL con nomi preceduti da @; i valori dei parametri vengono specificati nel parametro params di questa azione.

Per informazioni dettagliate sulla sintassi delle query Cloud Spanner, consulta Sintassi delle query.

Sintassi

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

Esempio

In questo esempio, una query recupera i valori delle colonne username e email dalla tabella user. L'istruzione SQL specifica un parametro postalCode impostato dalla variabile di flusso postal.code.value.

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

Parametri di richiesta

Parametro	Descrizione	Tipo	Predefinito	Obbligatorio
sql	La query SQL da eseguire. Puoi specificare i parametri con nomi di parametri preceduti da @. Questi nomi di parametri devono corrispondere alle chiavi nel parametro `params` di questa azione.	Stringa	Nessuno.	Sì.
params	Un oggetto le cui chiavi e valori sono i nomi e i valori dei parametri utilizzati nella query SQL. Puoi elencare più parametri qui.	Oggetto	Nessuno.	No.

Risposta

Un oggetto rows contenente un array di coppie nome-valore di colonne restituite dalla query. Ad esempio:

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

update

Aggiorna le righe nel database con i dati specificati.

Sintassi

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

Esempio

In questo esempio, l'indirizzo email dell'utente il cui username è Liz456 viene aggiornato con un nuovo valore. Una riga viene aggiornata.

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

Parametri di richiesta

Parametro	Descrizione	Tipo	Predefinito	Obbligatorio
nome tabella	La tabella del database in cui devono essere aggiornate le righe.	Stringa	Nessuno.	Sì.
righe	Un array di dati di riga da aggiornare. Ogni entità nell'array deve contenere il valore dell'ID univoco (ad esempio la chiave primaria) per la riga da aggiornare.	Array	Nessuno.	Sì.

Risposta

Nessuno.

Riferimento alla configurazione

Utilizza quanto segue quando configuri ed esegui il deployment di questa estensione per l'utilizzo nei proxy API. Per i passaggi per configurare un'estensione utilizzando la console Apigee, vedi Aggiunta e configurazione di un'estensione.

Proprietà comuni delle estensioni

Per ogni estensione sono presenti le seguenti proprietà.

Proprietà	Descrizione	Predefinito	Obbligatorio
`name`	Il nome che assegni a questa configurazione dell'estensione.	Nessuno	Sì
`packageName`	Nome del pacchetto dell'estensione fornito da Apigee Edge.	Nessuno	Sì
`version`	Numero di versione del pacchetto dell'estensione da cui stai configurando un'estensione.	Nessuno	Sì
`configuration`	Valore di configurazione specifico per l'estensione che stai aggiungendo. Vedi Proprietà per questo pacchetto di estensioni	Nessuno	Sì

Proprietà di questo pacchetto di estensioni

Specifica i valori per le seguenti proprietà di configurazione specifiche di questa estensione.

Proprietà	Descrizione	Predefinito	Obbligatorio
ID progetto	ID del progetto Google Cloud contenente il database.	Nessuno.	Sì.
instanceId	ID dell'istanza Cloud Spanner nel tuo progetto Google Cloud.	Nessuno.	Sì.
databaseId	ID del database Cloud Spanner.	Nessuno.	Sì.
credenziali	Se inserito nella console Apigee Edge, questo è il contenuto del file della chiave dell'account di servizio. Se inviato utilizzando l'API Management, è un valore codificato in base64 generato dal file delle chiavi del service account.	Nessuno.	Sì.