Cette page a été traduite par l'API Cloud Translation.

Extension de base de données Google Cloud Spanner

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

Version 2.0.0

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

Ce contenu fournit une documentation 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 une base de données.
Une fois que vous avez l'instance et une base de données, accordez l'autorisation d'accéder à votre base de données au compte de service GCP qui représente votre extension. Pour en savoir plus sur le rôle à utiliser, consultez la section 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.
Si vous disposez d'un compte de service autorisé au niveau d'accès souhaité pour votre base de données, générez une clé pour le compte de service à l'aide de la console GCP. Utilisez le contenu du fichier JSON de clé généré lorsque vous configurez cette extension.
Utilisez le contenu du fichier JSON de clé généré lorsque vous ajoutez et configurez l'extension à l'aide de la référence de 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 montrent comment configurer 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 nouvel 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 du nom d'utilisateur et de l'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éfinira probablement la valeur en fonction des paramètres de 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 à l'aide du 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 règle 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 nouvel 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
tableName	Table de la base de données dans laquelle les lignes doivent être insérées.	Chaîne	Aucune.	Oui.
lignes	Les lignes à insérer, exprimées sous la forme d'un 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 un @ placé devant leur nom. 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 la page 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 un @ placé devant leur nom. 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 correspondent aux noms et aux 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
tableName	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 (par exemple, la clé primaire) 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 spécifiques à cette extension.

Propriété	Description	Par défaut	Obligatoire
projectId	ID du projet GCP contenant la base de données.	Aucune.	Oui.
instanceId	ID de l'instance Cloud Spanner de votre projet GCP.	Aucune.	Oui.
databaseId	ID de la base de données Cloud Spanner.	Aucune.	Oui.
credentials	Lorsque vous le saisissez dans la console Apigee Edge, il s'agit du contenu de votre fichier de clé de compte de service. Lorsqu'il est envoyé via l'API de gestion, 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.