Estensione database Google Cloud Spanner

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. info

Versione 2.0.0

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:

  1. Crea un'istanza Cloud Spanner, come descritto in Creare e gestire istanze, e un database.

  2. Una volta che hai l'istanza e un database, concedi l'autorizzazione per accedere al database all'account di servizio Google Cloud che rappresenta la tua estensione. Per saperne di più sul ruolo da utilizzare, consulta la sezione Ruoli Cloud Spanner. Per saperne di più sul controllo dell'accesso di Cloud Spanner, consulta Applicare i ruoli IAM e Controllo dell'accesso per Cloud Spanner.

  3. Quando hai un account di servizio che dispone dell'autorizzazione per il livello di accesso al database che ti serve, 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.

  4. 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 i dati relazionali, strutturati e semistrutturati che richiedono alta disponibilità, elevata coerenza e letture e scritture transazionali.

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

Esempi

Gli esempi riportati di seguito mostrano come configurare il supporto per le azioni di estensione Cloud Spanner utilizzando il criterio ExtensionCallout.

Aggiungi datiOttieni datiAggiorna dati

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

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

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 della query. Ecco un esempio. Il criterio probabilmente imposta 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 come JSON, ad esempio come segue.

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

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.

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

Nell'esempio seguente, l'azione insert dell'estensione aggiunge un nuovo utente alla tabella utente. 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
tableName La tabella nel 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 specificati nell'istruzione SQL con nomi preceduti da @. I valori dei parametri sono specificati nel parametro params di questa azione.

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

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

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 i nomi dei parametri preceduti da @. Questi nomi di parametro devono corrispondere alle chiavi nel parametro params di questa azione. Stringa Nessuno. Sì.
params Un oggetto le cui chiavi e i cui valori sono i nomi e i valori dei parametri utilizzati nella query SQL. Qui puoi elencare più parametri. Oggetto Nessuno. No.

Risposta

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

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

update

Aggiorna le righe nel database con i dati specificati.

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

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

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

Parametri di richiesta

Parametro Descrizione Tipo Predefinito Obbligatorio
tableName 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 utilizzarla nei proxy API. Per la procedura di configurazione di 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à per 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, si tratta dei contenuti del file della chiave dell'account di servizio. Se inviato tramite l'API di gestione, è un valore codificato in base64 generato dal file della chiave dell'account di servizio. Nessuno. Sì.