Utilisation de l’API de données Amazon Redshift

Vous pouvez accéder à votre base de données Amazon Redshift en utilisant l’API de données Amazon Redshift intégrée. À l'aide de cette API, vous pouvez accéder aux données Amazon Redshift via des applications basées sur des services Web, notamment des blocs-notes AWS Lambda Amazon SageMaker et. AWS Cloud9 Pour plus d'informations sur ces applications AWS Lambda, consultez Amazon SageMaker et AWS Cloud9.

L’API de données ne nécessite pas de connexion permanente à votre base de données. Au lieu de cela, il fournit un point de terminaison HTTP sécurisé et une intégration avec AWS les SDK. Vous pouvez utiliser le point de terminaison pour exécuter des instructions SQL sans avoir à gérer de connexions. Les appels à l’API de données sont asynchrones.

L'API de données utilise soit des informations d'identification stockées dans la base de données, AWS Secrets Manager soit des informations d'identification temporaires. Il n’est pas nécessaire de transmettre des mots de passe dans les appels d’API avec l’une ou l’autre méthode d’autorisation. Pour plus d'informations AWS Secrets Manager, voir Qu'est-ce que c'est AWS Secrets Manager ? dans le guide de AWS Secrets Manager l'utilisateur.

Pour plus d’informations sur les fonctions de l’API de données, consultez la Référence de l’API de données Amazon Redshift.

Utilisation de l’API de données Amazon Redshift

Avant d’utiliser l’API de données Amazon Redshift, passez en revue les étapes suivantes :

1. Déterminez si vous, en tant qu’appelant de l’API de données, disposez des autorisations requises. Pour de plus amples informations concernant l’autorisation, consultez Autorisation de l’accès à l’API de données Amazon Redshift.

2. Déterminez si vous prévoyez d’appeler l’API de données avec les informations d’identification d’authentification de Secrets Manager ou avec des informations d’identification temporaires. Pour plus d’informations, consultez Choix des informations d’authentification de la base de données lors de l’appel de l’API de données Amazon Redshift..

3. Configurez un secret si vous utilisez Secrets Manager pour les informations d’identification d’authentification. Pour plus d’informations, consultez Stockage des identifiants de base de données dans AWS Secrets Manager.

4. Passez en revue les considérations et les limitations lors de l’appel de l’API de données. Pour plus d’informations, consultez Considérations relatives à l’appel à l’API de données Amazon Redshift.

5. Appelez l'API Data depuis AWS Command Line Interface (AWS CLI), depuis votre propre code ou à l'aide de l'éditeur de requêtes de la console Amazon Redshift. Pour des exemples d'appels depuis le AWS CLI, voirAppel à l’API de données.

Considérations relatives à l’appel à l’API de données Amazon Redshift

Tenez compte des éléments suivants lorsque vous appelez l’API de données :

• L’API de données Amazon Redshift peut accéder aux bases de données dans les clusters Amazon Redshift provisionnés et les groupes de travail Redshift sans serveur. Pour obtenir la liste des Régions AWS endroits où l'API Redshift Data est disponible, consultez les points de terminaison répertoriés pour l'API Redshift Data dans le. Référence générale d'Amazon Web Services

• La durée maximale d’une requête est de 24 heures.

• Le nombre maximal de requêtes actives (requêtes STARTED et SUBMITTED) par cluster Amazon Redshift est de 200.

• La taille maximale du résultat de la requête est de 100 Mo (après compression gzip). Si l’appel renvoie plus de 100 Mo de données de réponse, l’appel est arrêté.

• La durée maximale de conservation des résultats de la requête est de 24 heures.

• La taille maximale de l’instruction de requête est de 100 Ko.

• L’API de données est à même de lancer des requêtes sur des clusters à un ou plusieurs nœuds des types de nœuds suivants :

  • dc2.large

  • dc2.8xlarge

  • ra3.xlplus

  • ra3.4xlarge

  • ra3.16xlarge

• Le clusters doit être dans un cloud privé virtuel (VPC) basé sur le service Amazon VPC.

• Par défaut, les utilisateurs ayant le même rôle IAM ou les mêmes autorisations IAM que l’exécutant d’une fonction API ExecuteStatement ou BatchExecuteStatement peuvent agir sur la même déclaration avec des fonctions API CancelStatement, DescribeStatement, GetStatementResult et ListStatements. Pour agir sur la même instruction SQL provenant d’un autre utilisateur, l’utilisateur doit pouvoir assumer le rôle IAM de l’utilisateur qui a exécuté l’instruction SQL. Pour plus d’informations sur la façon d’assumer un rôle, consultez Autorisation de l’accès à l’API de données Amazon Redshift.

• Les instructions SQL du paramètre Sqls de l’opération d’API BatchExecuteStatement sont exécutées en tant que transaction unique. Ils s’exécutent en série dans l’ordre du tableau. Les instructions SQL suivantes ne démarrent pas tant que l’instruction précédente du tableau n’est pas terminée. Si une instruction SQL échoue, c’est parce qu’elle est exécutée comme une seule transaction que tout le travail est annulé.

• La durée de conservation maximale d’un jeton client utilisé dans une opération d’API ExecuteStatement ou BatchExecuteStatement est de 8 heures.

• Chaque API de l’API de données Redshift dispose d’un quota de transactions par seconde avant de limiter les demandes. Pour ce quota, consultez Quotas pour l’API de données Amazon Redshift. Si le taux de demande dépasse le quota, une exception ThrottlingException avec le code d’état HTTP : 400 est renvoyée. Pour répondre à la limitation, utilisez une stratégie de nouvelle tentative telle que décrite dans Comportement de nouvelle tentative, dans le Guide de référence des outils et des kits AWS SDK. Cette stratégie est mise en œuvre automatiquement pour limiter les erreurs dans certains AWS SDK.

  Note

  Par défaut AWS Step Functions, les nouvelles tentatives ne sont pas activées. Si vous devez appeler une API de données Redshift dans une machine d’état Step Functions, incluez le paramètre d’idempotence ClientToken dans votre appel d’API de données Redshift. La valeur de ClientToken doit être conservée entre les nouvelles tentatives. Dans l’exemple d’extrait suivant d’une demande adressée à l’API ExecuteStatement, l’expression States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7) utilise une fonction intrinsèque pour extraire la partie UUID de $$.Execution.Id, qui est unique pour chaque exécution de la machine d’état. Pour plus d’informations, consultez Fonctions intrinsèques dans le Guide du développeur AWS Step Functions .

  {
    "Database": "dev",
    "Sql": "select 1;",
    "ClusterIdentifier": "MyCluster",
    "ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
  }

Choix des informations d’authentification de la base de données lors de l’appel de l’API de données Amazon Redshift.

Lorsque vous appelez l’API de données, vous utilisez l’une des méthodes d’authentification suivantes pour certaines fonctions de l’API. Chaque méthode nécessite une combinaison différente de paramètres.

AWS Secrets Manager

Avec cette méthode, fournissez secret-arn le secret stocké dans AWS Secrets Manager lequel a username etpassword. Le secret spécifié contient des informations d’identification pour vous connecter à la database que vous spécifiez. Lorsque vous vous connectez à un cluster, vous fournissez également le nom de la base de données, Si vous fournissez un identifiant de cluster (dbClusterIdentifier), il doit correspondre à l’identifiant de cluster stocké dans le secret. Lorsque vous vous connectez à un groupe de travail sans serveur, vous devez également fournir le nom de la base de données. Pour plus d’informations, consultez Stockage des identifiants de base de données dans AWS Secrets Manager.

Informations d’identification temporaires

Avec cette méthode, choisissez l’une des options suivantes :

• Lors de la connexion à un groupe de travail sans serveur, indiquez le nom du groupe de travail et le nom de la base de données. Le nom de l’utilisateur de la base de données est dérivé de l’identité IAM. Par exemple, arn:iam::123456789012:user:foo a le nom d’utilisateur de la base de données IAM:foo. De plus, l’autorisation d’appeler l’opération redshift-serverless:GetCredentials est requise.

• Lorsque vous vous connectez à un cluster en tant qu’identité IAM, indiquez l’identifiant du cluster et le nom de la base de données. Le nom de l’utilisateur de la base de données est dérivé de l’identité IAM. Par exemple, arn:iam::123456789012:user:foo a le nom d’utilisateur de la base de données IAM:foo. De plus, l’autorisation d’appeler l’opération redshift:GetClusterCredentialsWithIAM est requise.

• Lorsque vous vous connectez à un cluster en tant qu’utilisateur de base de données, indiquez l’identifiant du cluster, le nom de la base de données et le nom de l’utilisateur de la base de données. De plus, l’autorisation d’appeler l’opération redshift:GetClusterCredentials est requise. Pour savoir comment rejoindre des groupes de base de données lors de la connexion avec cette méthode, consultez Rejoindre des groupes de base de données lors de la connexion à un cluster.

Avec ces méthodes, vous pouvez également fournir une region valeur qui indique l' Région AWS emplacement de vos données.

Mappage de types de données JDBC lors de l’appel à l’API de données Amazon Redshift

Le tableau suivant associe les types de données Java Database Connectivity (JDBC) aux types de données que vous spécifiez dans les appels d’API de données.

Type de données JDBC	Type de données API de données
INTEGER, SMALLINT, BIGINT	LONG
FLOAT, REAL, DOUBLE	DOUBLE
DECIMAL	STRING
BOOLEAN, BIT	BOOLEAN
BLOB, BINARY, LONGVARBINARY	BLOB
VARBINARY	STRING
CLOB	STRING
Autres types (y compris les types liés à la date et à l’heure)	STRING

Les valeurs de chaîne de caractères sont transmises à la base de données Amazon Redshift et implicitement converties en un type de données de base de données.

Note

Actuellement, l’API de données ne prend pas en charge les tableaux d’identificateurs uniques universels (UUID).

Exécution d’instructions SQL avec des paramètres lors de l’appel à l’API de données Amazon Redshift

Vous pouvez contrôler le texte SQL soumis au moteur de la base de données en appelant la fonction de l’API de données tout en utilisant des paramètres pour les parties de l’instruction SQL. Les paramètres nommés constituent un moyen flexible de passer des paramètres sans les coder en dur dans le texte. Ils vous aident à réutiliser le texte SQL et à éviter les problèmes d’injection SQL.

L'exemple suivant montre les paramètres nommés d'un parameters champ d'une execute-statement AWS CLI commande.

--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"

Tenez compte des éléments suivants lorsque vous utilisez des paramètres nommés :

• Les paramètres nommés ne peuvent être utilisés que pour remplacer des valeurs dans les instructions SQL.

  • Vous pouvez remplacer les valeurs d’une instruction INSERT, telle que INSERT INTO mytable VALUES(:val1).

    Les paramètres nommés peuvent être dans n’importe quel ordre et ils peuvent être utilisés plusieurs fois dans le texte SQL. L’option de paramétrage présentée dans un précédent exemple, les valeurs 1 et Seattle sont insérées dans les colonnes id et address de la table. Dans le texte SQL, vous spécifiez les paramètres nommés comme suit :

    --sql "insert into mytable values (:id, :address)"

  • Vous pouvez remplacer les valeurs dans une clause de condition, telle que WHERE attr >= :val1, WHERE attr BETWEEN :val1 AND :val2 et HAVING COUNT(attr) > :val.

  • Vous ne pouvez pas remplacer les noms de colonnes dans une instruction SQL, tels que SELECT column-name, ORDER BY column-name, ou GROUP BY column-name.

    Par exemple, l’instruction SELECT suivante échoue en raison d’une syntaxe non valide.

    --sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]"

    Si vous décrivez (opération describe-statement) l’instruction avec l’erreur de syntaxe, la commande QueryString renvoyée ne remplace pas le nom de la colonne par le paramètre ("QueryString": "SELECT :colname, FROM event") et une erreur est signalée (ERREUR : erreur de syntaxe à ou près de « FROM » Position : 12).

  • Vous ne pouvez pas remplacer les noms de colonnes dans une fonction d’agrégation, tels que COUNT(column-name), AVG(column-name), ou SUM(column-name).

  • Vous ne pouvez pas remplacer les noms de colonnes dans une clause JOIN.

• Lorsque le SQL s’exécute, les données sont implicitement converties en un type de données. Pour plus d’informations sur le moulage des types de données, consultez Types de données dans le Manuel du développeur de base de données Amazon Redshift.

• Vous ne pouvez pas définir une valeur sur NULL. L’API de données l’interprète comme la chaîne littérale NULL. L’exemple suivant remplace id par la chaîne littérale null. Pas la valeur SQL NULL.

  --parameters "[{\"name\": \"id\", \"value\": \"null\"}]"

• Vous ne pouvez pas définir une valeur de longueur de zéro. L’instruction SQL de l’API de données échoue. L’exemple suivant tente de définir id avec une valeur de longueur de zéro et se solde par un échec de l’instruction SQL.

  --parameters "[{\"name\": \"id\", \"value\": \"\"}]"

• Vous ne pouvez pas définir un nom de table dans l’instruction SQL avec un paramètre. L’API de données suit la règle du JDBC PreparedStatement.

• La sortie de l’opération describe-statement renvoie les paramètres de requête d’une instruction SQL.

• Seule l’opération execute-statement prend en charge les instructions SQL avec des paramètres.

Exécution d’instructions SQL avec un jeton d’idempotence lors de l’appel à l’API de données Amazon Redshift

Lorsque vous effectuez une demande d’API de mutation, la demande renvoie généralement un résultat avant la fin des flux de travail asynchrones de l’opération. Les opérations peuvent également expirer ou rencontrer d’autres problèmes de serveur avant d’être terminées, même si la demande a déjà renvoyé un résultat. Par conséquent, il peut être difficile de déterminer si la demande a abouti ou non et de multiples tentatives peuvent être déclenchées pour s’assurer que l’opération se termine correctement. Toutefois, si la demande initiale et les tentatives suivantes aboutissent, l’opération est terminée plusieurs fois. Vous pouvez ainsi mettre à jour plus de ressources que prévu.

L’idempotence garantit qu’une demande d’API se termine correctement. Avec une demande idempotente, si la demande d’origine se termine avec succès, toutes les tentatives suivantes se terminent avec succès, sans aucune action supplémentaire. Les opérations ExecuteStatement et BatchExecuteStatement de l’API de données ont un paramètre idempotent ClientToken facultatif. Le ClientToken expire au bout de 8 heures.

Important

Si vous appelez ExecuteStatement et effectuez BatchExecuteStatement des opérations à partir d'un AWS SDK, celui-ci génère automatiquement un jeton client à utiliser lors d'une nouvelle tentative. Dans ce cas, nous ne recommandons pas d’utiliser le paramètre client-token avec les opérations ExecuteStatement et BatchExecuteStatement. Consultez le CloudTrail journal pour voir leClientToken. Pour un exemple de CloudTrail journal, voirExemples d’API de données Amazon Redshift.

La execute-statement AWS CLI commande suivante illustre le client-token paramètre facultatif pour l'idempotentie.

aws redshift-data execute-statement 
    --region us-west-2 
    --secret arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn 
    --cluster-identifier mycluster-test 
    --sql "select * from stl_query limit 1" 
    --database dev 
    --client-token b855dced-259b-444c-bc7b-d3e8e33f94g1                       

La table suivante présente certaines réponses courantes que vous pouvez obtenir pour les demandes d’API idempotentes et fournit des recommandations pour réessayer.

Réponse	Recommandation	Commentaires
200 (OK)	Ne pas réessayer	La demande d’origine s’est terminée avec succès. Toutes les tentatives suivantes sont renvoyées avec succès.
Codes de réponse de la série 400	Ne pas réessayer	La demande présente un problème, parmi les suivants : Elle inclut un paramètre ou une combinaison de paramètres invalide. Elle utilise une action ou une ressource pour laquelle vous n’avez pas les autorisations nécessaires. Elle utilise une ressource qui est en train de changer d’état. Si la demande concerne une ressource en train de changer d’état, il est possible que la nouvelle tentative aboutisse.
Codes de réponse de la série 500	Réessayer	L'erreur est due à un problème AWS côté serveur et est généralement transitoire. Répétez la demande avec une stratégie de backoff appropriée.

Pour plus d’informations sur les codes de réponse Amazon Redshift, consultez Common Errors (Erreurs courantes) dans la référence d’API Amazon Redshift.