Extension de base de données Google Cloud Spanner

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Version 2.0.2

Effectuez des opérations d'insertion, d'interrogation et de mise à jour sur une base de données Cloud Spanner.

Ce contenu fournit des informations de référence pour configurer et utiliser cette extension. Avant d'utiliser l'extension à partir d'un proxy d'API à l'aide de la règle ExtensionCallout, vous devez :

Créez une instance Cloud Spanner, comme décrit dans Créer et gérer des instances, puis créez une base de données.
Une fois que vous disposez de l'instance et d'une base de données, accordez l'autorisation d'accéder à votre base de données au compte de service Google Cloud qui représente votre extension. Pour en savoir plus sur le rôle à utiliser, consultez Rôles Cloud Spanner. Pour en savoir plus sur le contrôle des accès à Cloud Spanner, consultez Appliquer des rôles IAM et Contrôle des accès pour Cloud Spanner.
Une fois que vous disposez d'un compte de service autorisé à accéder à votre base de données au niveau souhaité, utilisez la console Google Cloud pour générer une clé pour le compte de service. Utilisez le contenu du fichier JSON de clé obtenu lorsque vous configurez cette extension.
Utilisez le contenu du fichier JSON de clé obtenu lorsque vous ajoutez et configurez l'extension à l'aide de la documentation de référence sur la configuration.

À propos de Cloud Spanner

Cloud Spanner est un service de base de données relationnelle utile pour les données relationnelles, structurées et semi-structurées qui exigent une haute disponibilité, une cohérence forte, ainsi que des lectures et des écritures transactionnelles.

Si vous débutez avec Cloud Spanner, le guide de démarrage rapide de la documentation Cloud Spanner est un bon point de départ.

Exemples

Les exemples suivants illustrent la configuration de la prise en charge des actions d'extension Cloud Spanner à l'aide de la règle ExtensionCallout.

Ajouter des données

Dans l'exemple suivant, l'action insert de l'extension ajoute un utilisateur à la table des utilisateurs.

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

Obtenir les données

Dans cet exemple, une requête récupère les valeurs de nom d'utilisateur et d'adresse e-mail à partir de la table user.

Tout d'abord, une règle AssignMessage attribue une variable postal.code.value à utiliser dans une clause WHERE de requête. Voici un exemple. Votre règle définirait probablement la valeur en fonction des paramètres de la requête 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>

La règle ExtensionCallout suivante exécute une requête sur la base de données, en utilisant le contenu de la variable postal.code.value dans la clause 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>

La stratégie AssignMessage suivante utilise ensuite la réponse de l'extension, stockée dans la variable spanner.userdata.retrieved, comme réponse renvoyée au 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>

Dans cet exemple, les données de réponse sont renvoyées au format JSON, comme suit.

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

Mettre à jour des données

Dans cet exemple, l'élément <Input> contient username (la clé primaire de la table) et une nouvelle valeur pour la colonne 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>

Actions

insert

Insère les lignes spécifiées dans la base de données.

Syntaxe

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

Exemple

Dans l'exemple suivant, l'action insert de l'extension ajoute un utilisateur à la table des utilisateurs. Une ligne est ajoutée.

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

Paramètres de requête

Paramètre	Description	Type	Valeur par défaut	Obligatoire
nom de la table	Table de la base de données dans laquelle les lignes doivent être insérées.	Chaîne	Aucune.	Oui.
lignes	Lignes à insérer exprimées sous forme de tableau dans un objet JSON `rows`.	Tableau	Aucune.	Oui.

Réponse

Aucune.

querySQL

Interroge la base de données à l'aide de l'instruction SQL avec les paramètres spécifiés. Les paramètres sont indiqués dans l'instruction SQL avec des noms précédés d'un @. Les valeurs des paramètres sont spécifiées dans le paramètre params de cette action.

Pour en savoir plus sur la syntaxe des requêtes Cloud Spanner, consultez Syntaxe des requêtes.

Syntaxe

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

Exemple

Dans cet exemple, une requête récupère les valeurs des colonnes username et email de la table user. L'instruction SQL spécifie un paramètre postalCode défini à partir de la variable de flux postal.code.value.

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

Paramètres de requête

Paramètre	Description	Type	Valeur par défaut	Obligatoire
sql	Requête SQL à exécuter. Vous pouvez spécifier des paramètres avec des noms de paramètres précédés d'un @. Ces noms de paramètres doivent correspondre aux clés du paramètre `params` de cette action.	Chaîne	Aucune.	Oui.
params	Objet dont les clés et les valeurs sont les noms et les valeurs des paramètres utilisés dans la requête SQL. Vous pouvez lister plusieurs paramètres ici.	Objet	Aucune.	Non.

Réponse

Objet rows contenant un tableau de paires nom/valeur de colonne renvoyées par la requête. Exemple :

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

update

Met à jour les lignes de la base de données avec les données spécifiées.

Syntaxe

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

Exemple

Dans cet exemple, l'adresse e-mail de l'utilisateur dont l'username est Liz456 est remplacée par une nouvelle valeur. Une ligne est mise à jour.

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

Paramètres de requête

Paramètre	Description	Type	Valeur par défaut	Obligatoire
nom de la table	Table de la base de données dans laquelle les lignes doivent être mises à jour.	Chaîne	Aucune.	Oui.
lignes	Tableau de données de ligne à mettre à jour. Chaque entité du tableau doit contenir la valeur de l'ID unique (clé primaire, par exemple) de la ligne à mettre à jour.	Tableau	Aucune.	Oui.

Réponse

Aucune.

Documentation de référence sur la configuration

Utilisez les éléments suivants lorsque vous configurez et déployez cette extension pour l'utiliser dans des proxys d'API. Pour savoir comment configurer une extension à l'aide de la console Apigee, consultez Ajouter et configurer une extension.

Propriétés d'extension courantes

Les propriétés suivantes sont présentes pour chaque extension.

Propriété	Description	Par défaut	Obligatoire
`name`	Nom que vous attribuez à cette configuration de l'extension.	Aucune	Oui
`packageName`	Nom du package d'extension tel qu'indiqué par Apigee Edge.	Aucune	Oui
`version`	Numéro de version du package d'extension à partir duquel vous configurez une extension.	Aucune	Oui
`configuration`	Valeur de configuration spécifique à l'extension que vous ajoutez. Consultez Propriétés de ce package d'extension.	Aucune	Oui

Propriétés de ce package d'extension

Spécifiez les valeurs des propriétés de configuration suivantes propres à cette extension.

Propriété	Description	Par défaut	Obligatoire
projectId	ID du projet Google Cloud contenant la base de données.	Aucune.	Oui.
instanceId	ID de l'instance Cloud Spanner dans votre projet Google Cloud.	Aucune.	Oui.
databaseId	ID de la base de données Cloud Spanner.	Aucune.	Oui.
identifiants	Lorsqu'il est saisi dans la console Apigee Edge, il s'agit du contenu de votre fichier de clé de compte de service. Lorsqu'il est envoyé à l'aide de l'API Management, il s'agit d'une valeur encodée en base64 générée à partir du fichier de clé du compte de service.	Aucune.	Oui.