Amazon Redshift ne prendra plus en charge la création de nouveaux Python à UDFs partir du patch 198. UDFs Le Python existant continuera de fonctionner jusqu'au 30 juin 2026. Pour plus d’informations, consultez le [ billet de blog ](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/).
Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Utilisation de l’API de données Amazon Redshift
L’API de données Amazon Redshift simplifie l’accès à votre entrepôt de données Amazon Redshift en éliminant le besoin de gérer les pilotes de base de données, les connexions, les configurations réseau, la mise en mémoire tampon des données, les informations d’identification, etc. Vous pouvez exécuter des instructions SQL à l'aide des opérations de l'API de données avec le AWS SDK. 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](https://docs.aws.amazon.com/redshift-data/latest/APIReference/).
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 SDKs. 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 peut utiliser des informations d'identification stockées dans AWS Secrets Manager ou des informations d'identification temporaires dans la base de données. 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 ?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) dans le *guide de AWS Secrets Manager l'utilisateur*. Vous pouvez également utiliser AWS IAM Identity Center pour obtenir une autorisation.
Avec l'API Data, vous pouvez accéder par programmation aux données Amazon Redshift à l'aide d'applications basées sur des services Web AWS Lambda, notamment les blocs-notes Amazon SageMaker AI et. AWS Cloud9 Pour plus d'informations sur ces applications [AWS Lambda](https://aws.amazon.com/lambda/), consultez [Amazon SageMaker AI](https://aws.amazon.com/sagemaker/) et [AWS Cloud9](https://aws.amazon.com/cloud9/).
Pour en savoir plus sur l’API de données, consultez [Mise en route avec l’API de données Amazon Redshift](https://aws.amazon.com/blogs/big-data/get-started-with-the-amazon-redshift-data-api/) sur le le blog *AWS Big Data*.
## 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](data-api-access.md).
1. Déterminez si vous prévoyez d’appeler l’API de données avec les informations d’identification d’authentification de Secrets Manager, avec des informations d’identification temporaires ou avec AWS IAM Identity Center. Pour de plus amples informations, veuillez consulter [Choix des informations d’authentification de la base de données lors de l’appel de l’API de données Amazon Redshift.](#data-api-calling-considerations-authentication).
1. 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](data-api-secrets.md).
1. Passez en revue les considérations et les limitations lors de l’appel de l’API de données. Pour de plus amples informations, veuillez consulter [Considérations relatives à l’appel à l’API de données Amazon Redshift](#data-api-calling-considerations).
1. 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 obtenir des exemples d’appel depuis AWS CLI, consultez [Appel à l’API de données](data-api-calling.md).
## 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](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html) 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 maximum de requêtes (`STARTED`et `SUBMITTED` requêtes) actives par cluster Amazon Redshift est de 500.
+ La taille maximale du résultat de requête est de 500 Mo (après compression gzip). Si un appel renvoie plus de 500 Mo de données de réponse, l'appel est terminé.
+ 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.large
+ 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 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`, `GetStatementResultV2` 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](data-api-access.md).
+ 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.
+ Si les clusters provisionnés par Amazon Redshift et le groupe de travail Redshift Serverless sont chiffrés à l'aide d'une clé gérée par le client, Redshift crée une autorisation qui permet à l'API Redshift Data d'utiliser la clé pour ses opérations. Pour plus d'informations, consultez [Utilisation AWS KMS avec l'API de données Amazon Redshift](data-api-kms.md).
+ 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](amazon-redshift-limits.md#data-api-quotas-account). 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 la section [Comportement des nouvelles tentatives](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) dans le guide de référence *AWS SDKs and* Tools. Cette stratégie est mise en œuvre automatiquement pour limiter les erreurs dans certains cas. AWS SDKs
**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](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-intrinsic-functions.html) 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 IAM Identity Center**
L’API de données est accessible avec un utilisateur à authentification unique enregistré dans AWS IAM Identity Center. Pour plus d’informations sur les étapes de configuration d’IAM Identity Center, consultez [Utilisation de l’API de données avec la propagation d’identité de confiance](data-api-trusted-identity-propagation.md).
**AWS Secrets Manager**
Avec cette méthode, fournissez `secret-arn` le secret stocké dans AWS Secrets Manager lequel a `username` et`password`. 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 de plus amples informations, veuillez consulter [Stockage des identifiants de base de données dans AWS Secrets Manager](data-api-secrets.md).
Avec cette méthode, vous pouvez également fournir une `region` valeur qui indique l' Région AWS emplacement de vos données.
**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](data-api-dbgroups.md).
Avec cette méthode, 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 Data ne prend pas en charge les tableaux d'identifiants uniques universels ()UUIDs.
## 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](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html) 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 le`ClientToken`. Pour un exemple de CloudTrail journal, voir[Exemples d’API de données Amazon Redshift](logging-with-cloudtrail.md#data-api-cloudtrail).
La `execute-statement` AWS CLI commande suivante illustre le `client-token` paramètre facultatif pour l'idempotentie.
```
aws redshift-data execute-statement
--secret-arn 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 | Recommendation | 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 : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/redshift/latest/mgmt/data-api.html) 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](https://docs.aws.amazon.com/redshift/latest/APIReference/CommonErrors.html) (Erreurs courantes) dans la *référence d’API Amazon Redshift*.
## Exécution d’instructions SQL avec réutilisation de session lors de l’appel à l’API de données Amazon Redshift
Lorsque vous faites une demande d’API pour exécuter une instruction SQL, la session pendant laquelle le SQL s’exécute est généralement interrompue lorsque le SQL est terminé. Pour que la session reste active pendant un certain nombre de secondes, les opérations d’API de données `ExecuteStatement` et `BatchExecuteStatement` ont un paramètre `SessionKeepAliveSeconds` facultatif. Un champ de réponse `SessionId` contient l’identité de la session qui peut ensuite être utilisée dans les opérations `ExecuteStatement` et `BatchExecuteStatement` suivantes. Lors des appels suivants, vous pouvez en spécifier un autre `SessionKeepAliveSeconds` pour modifier le délai d’inactivité. Si le `SessionKeepAliveSeconds` n’est pas modifié, le paramètre de délai d’inactivité initial est conservé. Tenez compte des éléments suivants lorsque vous utilisez la réutilisation de session :
+ La valeur maximale de `SessionKeepAliveSeconds` est de 24 heures.
+ La session peut durer 24 heures au maximum. Après 24 heures, la session est fermée de force et les requêtes en cours sont interrompues.
+ Le nombre maximum de sessions par cluster Amazon Redshift ou groupe de travail Redshift sans serveur est de 500.
+ Vous ne pouvez exécuter qu’une seule requête à la fois dans une session. Vous devez attendre la fin de la requête pour exécuter la requête suivante au cours de la même session. En d’autres termes, vous ne pouvez pas exécuter de requêtes en parallèle dans une session donnée.
+ L’API de données ne peut pas mettre les requêtes en file d’attente pour une session donnée.
Pour récupérer l’`SessionId` utilisé par les appels aux opérations `ExecuteStatement` et `BatchExecuteStatement`, l’appel `DescribeStatement` et les opérations `ListStatements`.
L’exemple suivant montre comment utiliser les paramètres `SessionKeepAliveSeconds` et `SessionId` pour maintenir une session active et la réutiliser. Appelez d'abord la `execute-statement` AWS CLI commande avec le `session-keep-alive-seconds` paramètre optionnel défini sur`2`.
```
aws redshift-data execute-statement
--session-keep-alive-seconds 2
--sql "select 1"
--database dev
--workgroup-name mywg
```
La réponse contient l’identifiant de session.
```
{
"WorkgroupName": "mywg",
"CreatedAt": 1703022996.436,
"Database": "dev",
"DbUser": "awsuser",
"Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680",
"SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4"
}
```
Appelez ensuite la `execute-statement` AWS CLI commande avec le résultat `SessionId` renvoyé par le premier appel. Et éventuellement, spécifiez le paramètre `session-keep-alive-seconds` défini sur `10` pour modifier la valeur du délai d’inactivité.
```
aws redshift-data execute-statement
--sql "select 1"
--session-id 5a254dc6-4fc2-4203-87a8-551155432ee4
--session-keep-alive-seconds 10
```
## Récupération des résultats des instructions SQL
Vous utilisez différentes opérations de l’API de données pour récupérer les résultats SQL en fonction du format des résultats. Lorsque vous appelez `ExecuteStatement` et effectuez les opérations `BatchExecuteStatement`, vous pouvez spécifier si les résultats sont au format JSON ou CSV. Si vous ne spécifiez rien, le format par défaut est JSON. Pour récupérer les résultats JSON, utilisez l’opération `GetStatementResult`. Pour récupérer les résultats CSV, utilisez l’opération `GetStatementResultV2`.
Les résultats renvoyés au format JSON sont des enregistrements qui incluent des métadonnées relatives à chaque colonne. Chaque enregistrement est au format JSON. Par exemple, la réponse de `GetStatementResult` ressemble à ceci :
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"longValue": 1
}
]
],
"TotalNumRows":
}
```
Les résultats renvoyés au format CSV sont des enregistrements qui incluent des métadonnées relatives à chaque colonne. Les résultats sont renvoyés sous forme de blocs de 1 Mo, chaque bloc pouvant stocker un nombre illimité de lignes au format CSV. Chaque requête renvoie jusqu’à 15 Mo de résultats. Si les résultats sont supérieurs à 15 Mo, un jeton de page suivante est renvoyé pour continuer à récupérer les résultats. Par exemple, la réponse de `GetStatementResultV2` ressemble à ceci :
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"CSVRecords":"1,2,3\r\n4,5,6\r\n7,8,9\rn, .... 1MB" // First 1MB Chunk
},
{
"CSVRecords":"1025,1026,1027\r\n1028,1029,1030\r\n....2MB" // Second 1MB chunk
}
...
]
],
"ResultFormat" : "CSV",
"TotalNumRows":
}
```
# Autorisation de l’accès à l’API de données Amazon Redshift
Pour accéder à l’API de données, un utilisateur doit recevoir une autorisation. Vous pouvez autoriser un utilisateur à accéder à l’API de données en ajoutant une politique gérée, qui est une politique Gestion des identités et des accès AWS (IAM) prédéfinie, à l’utilisateur concerné. Il est recommandé d’associer des politiques d’autorisation à un rôle IAM, puis de l’attribuer à des utilisateurs et à des groupes, le cas échéant. Pour plus d’informations, consultez [Identity and Access Management dans Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html). Pour connaître les autorisations autorisées et refusées par les politiques gérées, consultez la console IAM ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)).
# Configuration des autorisations IAM
Amazon Redshift fournit la politique gérée par `AmazonRedshiftDataFullAccess`. Cette politique fournit un accès complet aux fonctions de l’API de données Amazon Redshift. Cette politique permet également un accès limité à des opérations spécifiques d'Amazon Redshift AWS Secrets Manager et d'API IAM nécessaires pour authentifier et accéder à un cluster Amazon Redshift ou à un groupe de travail Redshift Serverless.
Vous pouvez également créer votre propre politique IAM qui autorise l’accès à des ressources spécifiques. Pour créer votre politique, utilisez la politique `AmazonRedshiftDataFullAccess` comme modèle de départ. Une fois votre politique créée, ajoutez-la à chaque utilisateur ayant besoin d’accéder à l’API de données.
Prenez les exigences suivantes de la politique IAM associée à l’utilisateur :
+ Si vous utilisez cette AWS Secrets Manager option pour vous authentifier, vérifiez que la politique autorise l'utilisation de l'`secretsmanager:GetSecretValue`action pour récupérer le secret associé à la clé`RedshiftDataFullAccess`.
+ Si vous utilisez des informations d’identification temporaires pour vous authentifier auprès d’un cluster, confirmez que la politique autorise l’utilisation de l’action `redshift:GetClusterCredentials` pour le nom d’utilisateur de la base de données `redshift_data_api_user` pour toute base de données du cluster. Ce nom d’utilisateur doit déjà avoir été créé dans votre base de données.
+ Si vous utilisez des informations d’identification temporaires pour vous authentifier auprès d’un groupe de travail sans serveur, confirmez que la politique autorise l’utilisation de l’action `redshift-serverless:GetCredentials` pour récupérer le groupe de travail identifié avec la clé `RedshiftDataFullAccess`. L'utilisateur de la base de données est mappé 1:1 à l'identité source Gestion des identités et des accès AWS (IAM). Par exemple, l’utilisateur sample\$1user est mappé à l’utilisateur de la base de données `IAM:sample_user`, et le rôle IAM sample\$1role est mappé à `IAMR:sample_role`. Pour plus d’informations sur les identités IAM, consultez [Identités IAM (utilisateurs, groupes d’utilisateurs et rôles)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html) dans le Guide de l’utilisateur IAM.
+ L’action IAM `redshift-data:GetStatementResult` permet d’accéder à la fois aux opérations d’API `GetStatementResult` et `GetStatementResultV2`.
Les liens suivants fournissent des informations supplémentaires sur Gestion des identités et des accès AWS le *guide de l'utilisateur IAM*.
+ Pour plus d’informations sur la création de rôles IAM, consultez [Création de rôles IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html).
+ Pour plus d’informations sur la création de politiques IAM, consultez [Création de politiques IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html).
+ Pour en savoir plus sur l’ajout d’une politique IAM à un utilisateur, consultez [Ajout et suppression d’autorisations basées sur l’identité IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html).
## Exécution d’une requête sur un cluster appartenant un autre compte
Pour exécuter une requête sur un cluster appartenant à un autre compte, le compte propriétaire doit fournir un rôle IAM que l’API de données peut assumer dans le compte appelant. Par exemple, supposons que le compte B possède un cluster auquel le compte A doit accéder. Le compte B peut associer la politique AWS gérée `AmazonRedshiftDataFullAccess` au rôle IAM du compte B. Ensuite, le compte B approuve le compte A à l’aide d’une politique de confiance telle que la suivante : ``
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/someRoleA"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Enfin, le rôle IAM du compte A doit être en mesure d’assumer le rôle IAM du compte B.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/someRoleB"
}
}
```
------
## Spécifiez un rôle IAM qui limite les ressources aux groupes de travail Redshift Serverless et aux clusters Amazon Redshift dans un Compte AWS
Vous pouvez spécifier une ressource ARNs dans votre politique basée sur l'identité pour contrôler l'accès aux groupes de travail Redshift Serverless et aux clusters Amazon Redshift dans un. Compte AWS Cet exemple montre comment créer une politique qui autorise l’accès à l’API de données uniquement pour le groupe de travail et les clusters spécifiés Compte AWS.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "redshift-data:*",
"Resource": [
"arn:aws:redshift:us-east-1:111122223333:workgroup/*",
"arn:aws:redshift:us-east-1:111122223333:cluster:*"
]
}
]
}
```
------
## Configurer une politique IAM qui restreint l’accès aux informations des instructions SQL au seul propriétaire de l’instruction
Par défaut, l’API de données Amazon Redshift considère le rôle IAM utilisé lors de l’appel `ExecuteStatement` et `BatchExecuteStatement` comme le propriétaire de l’instruction SQL. Toute personne autorisée à assumer ce rôle peut accéder aux informations relatives à l’instruction SQL, notamment à ses résultats. Pour restreindre l’accès aux informations des instructions SQL à une session de rôle IAM avec un propriétaire particulier, ajoutez une condition `redshift-data:statement-owner-iam-userid: "${aws:userid}"`. La politique IAM suivante restreint l’accès.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:statement-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
Vous pouvez utiliser la condition `statement-owner-iam-userid` avec `CancelStatement`, `DescribeStatement`, `GetStatementResult` et `ListStatements`. Pour plus d’informations, consultez [Actions définies par l’API de données Amazon Redshift](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid).
## Configurer une politique IAM qui limite l’accès aux résultats SQL au seul propriétaire de la session
Par défaut, l’API de données Amazon Redshift considère le rôle IAM utilisé lors de l’appel `ExecuteStatement` et `BatchExecuteStatement` comme le propriétaire de la session de base de données qui exécute l’instruction SQL. Toute personne autorisée à assumer ce rôle peut soumettre des requêtes à la session de base de données. Pour restreindre l’accès à la session à une session de rôle IAM avec un propriétaire particulier, ajoutez une condition ` redshift-data:session-owner-iam-userid: "${aws:userid}"`. La politique IAM suivante restreint l’accès.
La politique IAM suivante permet uniquement au propriétaire de la session d’obtenir les résultats des instructions. La condition `session-owner-iam-userid` est utilisée pour limiter l’accès aux ressources au `userid` spécifié.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:ExecuteStatement",
"redshift-data:BatchExecuteStatement"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:session-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
Vous pouvez utiliser la condition `session-owner-iam-userid` avec `ExecuteStatement` et `BatchExecuteStatement`. Pour plus d’informations, consultez [Actions définies par l’API de données Amazon Redshift](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid).
# Stockage des identifiants de base de données dans AWS Secrets Manager
Lorsque vous appelez l’API de données, vous pouvez utiliser un secret dans AWS Secrets Manager pour transmettre les informations d’identification du cluster ou du groupe de travail sans serveur. Pour ce faire, vous devez spécifier le nom du secret ou son ARN (Amazon Resource Name).
Pour stocker des informations d’identification avec Secrets Manager, vous devez disposer d’une autorisation de politique gérée par `SecretManagerReadWrite`. Pour plus d'informations sur les autorisations minimales, consultez la section [Création et gestion de AWS secrets avec Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) dans le *guide de AWS Secrets Manager l'utilisateur*.
**Pour sauvegarder vos informations d'identification dans un secret pour un cluster Amazon Redshift**
1. Utilisez la AWS Secrets Manager console pour créer un secret contenant les informations d'identification de votre cluster :
+ Lorsque vous choisissez **Store a new secret (Sauvegarder un nouveau secret)**, sélectionnez **Credentials for Redshift cluster (Informations d'identification du cluster Redshift)**.
+ Sauvegardez les valeurs **User name (Nom d’utilisateur)** (utilisateur de la base de données), **Password (Mot de passe)** et **DB cluster (Cluster de base de données)** (identifiant du cluster) dans votre secret.
+ Étiquetez le secret avec la clé `RedshiftDataFullAccess`. La politique AWS gérée `AmazonRedshiftDataFullAccess` n'autorise l'action que `secretsmanager:GetSecretValue` pour les secrets marqués par la clé`RedshiftDataFullAccess`.
Pour obtenir des instructions, consultez [Création d’un secret basique](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) dans le *Guide de l’utilisateur AWS Secrets Manager *.
1. Utilisez la AWS Secrets Manager console pour afficher les détails du secret que vous avez créé ou exécutez la `aws secretsmanager describe-secret` AWS CLI commande.
Notez le nom et l’ARN du secret. Vous pouvez les utiliser dans les appels à l’API de données.
**Pour stocker vos informations d’identification dans un secret pour un groupe de travail sans serveur**
1. Utilisez AWS Secrets Manager AWS CLI des commandes pour stocker un secret contenant les informations d'identification de votre groupe de travail sans serveur :
+ Créez votre secret dans un fichier, par exemple, un fichier JSON nommé `mycreds.json`. Fournissez les valeurs du champ **User name** (Nom d’utilisateur), à savoir l’utilisateur de la base de données, et du champ **Password** (Mot de passe) dans le fichier.
```
{
"username": "myusername",
"password": "mypassword"
}
```
+ Stockez vos valeurs dans votre secret et étiquetez le secret avec la clé `RedshiftDataFullAccess`.
```
aws secretsmanager create-secret --name MyRedshiftSecret --tags Key="RedshiftDataFullAccess",Value="serverless" --secret-string file://mycreds.json
```
Le résultat est présenté ci-dessous :
```
{
"ARN": "arn:aws:secretsmanager:region:accountId:secret:MyRedshiftSecret-mvLHxf",
"Name": "MyRedshiftSecret",
"VersionId": "a1603925-e8ea-4739-9ae9-e509eEXAMPLE"
}
```
Pour plus d’informations, consultez [Création d’un secret basique avec AWS CLI](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html#proc-create-api) dans le *Guide de l’utilisateur AWS Secrets Manager *.
1. Utilisez la AWS Secrets Manager console pour afficher les détails du secret que vous avez créé ou exécutez la `aws secretsmanager describe-secret` AWS CLI commande.
Notez le nom et l’ARN du secret. Vous pouvez les utiliser dans les appels à l’API de données.
# Pour créer un point de terminaison Amazon VPC (AWS PrivateLink) pour l’API de données
Amazon Virtual Private Cloud (Amazon VPC) vous permet de lancer AWS des ressources, telles que des clusters et des applications Amazon Redshift, dans un cloud privé virtuel (VPC). AWS PrivateLink fournit une connectivité privée entre les clouds privés virtuels (VPCs) et les AWS services en toute sécurité sur le réseau Amazon. À l'aide de AWS PrivateLink, vous pouvez créer des points de terminaison VPC, que vous pouvez utiliser pour vous connecter à des services via différents comptes et VPCs sur la base d'Amazon VPC. Pour plus d'informations AWS PrivateLink, consultez la section [VPC Endpoint Services (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html) dans le guide de l'*utilisateur d'Amazon Virtual Private Cloud*.
Vous pouvez appeler l’API de données avec des points de terminaison Amazon VPC. L’utilisation d’un point de terminaison Amazon VPC permet de maintenir le trafic entre les applications de votre Amazon VPC et l’API de données dans le réseau AWS , sans utiliser d’adresses IP publiques. Les points de terminaison Amazon VPC peuvent vous aider à respecter les exigences réglementaires et de conformité liées à la limitation de la connectivité Internet publique. Par exemple, si vous utilisez un point de terminaison Amazon VPC, vous pouvez conserver le trafic entre une application exécutée sur une instance Amazon EC2 et l'API de données qui VPCs les contient.
Une fois que vous avez créé le point de terminaison Amazon VPC, vous pouvez commencer à l’utiliser sans modifier le code ou la configuration de votre application.
**Pour créer un point de terminaison Amazon VPC pour l’API de données**
1. Connectez-vous à la console Amazon VPC AWS Management Console et ouvrez-la à l'adresse. [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)
1. Choisissez **Points de terminaison**, puis **Créer un point de terminaison**.
1. Sur la page **Créer un point de terminaison**, pour **Catégorie de services**, choisissez **Services AWS **. Pour **Service Name (Nom de service)**, choisissez **redshift-data**(`com.amazonaws.region.redshift-data`).
1. Pour **VPC**, choisissez le VPC dans lequel créer le point de terminaison.
Choisissez le VPC contenant l’application qui effectue des appels de l’API de données.
1. Pour les **sous-réseaux**, choisissez le sous-réseau pour chaque zone de disponibilité (AZ) utilisée par le AWS service qui exécute votre application.
Pour créer un point de terminaison Amazon VPC, spécifiez la plage d’adresses IP privées dans laquelle le point de terminaison est accessible. Pour ce faire, choisissez le sous-réseau de chaque zone de disponibilité. Cela limite le point de terminaison de VPC à la plage d’adresses IP privées spécifique à chaque zone de disponibilité et crée également un point de terminaison Amazon VPC dans chaque zone de disponibilité.
1. Pour **Enable DNS Name (Activer le nom DNS)**, sélectionnez **Activer pour ce point de terminaison**.
Private DNS résout le nom d’hôte DNS standard de l’API de données (`https://redshift-data.region.amazonaws.com`) par les adresses IP privées associées au nom d’hôte DNS spécifique à votre point de terminaison Amazon VPC. Par conséquent, vous pouvez accéder au point de terminaison VPC de l'API de données en utilisant AWS CLI ou AWS SDKs sans apporter de modifications de code ou de configuration pour mettre à jour l'URL du point de terminaison de l'API de données.
1. Pour **Groupe de sécurité**, choisissez un groupe de sécurité à associer au point de terminaison Amazon VPC.
Choisissez le groupe de sécurité qui autorise l'accès au AWS service qui exécute votre application. Par exemple, si une instance Amazon EC2 exécute votre application, choisissez le groupe de sécurité qui autorise l’accès à cette instance Amazon EC2. Le groupe de sécurité vous permet de contrôler le trafic vers le point de terminaison Amazon VPC à partir des ressources de votre VPC.
1. Choisissez **Créer un point de terminaison**.
Une fois le point de terminaison créé, choisissez le lien dans le AWS Management Console pour afficher les détails du point de terminaison.
L’onglet **Détails** du point de terminaison affiche les noms d’hôte DNS générés lors de la création du point de terminaison Amazon VPC.
Vous pouvez utiliser le point de terminaison standard (`redshift-data.region.amazonaws.com`) ou l’un des points de terminaison spécifiques au VPC pour appeler l’API de données dans l’Amazon VPC. Le point de terminaison standard de l’API de données effectue automatiquement un routage vers le point de terminaison Amazon VPC. Ce routage se produit car le nom d’hôte DNS privé a été activé lors de la création du point de terminaison Amazon VPC.
Lorsque vous utilisez un point de terminaison Amazon VPC dans un appel d'API de données, tout le trafic entre votre application et l'API de données reste dans l'Amazon VPCs qui les contient. Vous pouvez utiliser un point de terminaison Amazon VPC pour n’importe quel type d’appel à l’API de données. Pour plus d’informations sur l’appel de l’API de données, consultez [Considérations relatives à l’appel à l’API de données Amazon Redshift](data-api.md#data-api-calling-considerations).
# Rejoindre des groupes de base de données lors de la connexion à un cluster
Les groupes de base de données sont des ensembles d’utilisateurs de base de données. Des privilèges de base de données peuvent être accordés aux groupes. Un administrateur peut configurer un rôle IAM de telle sorte que ces groupes de base de données soient pris en compte lorsque votre requête SQL s’exécute avec l’API de données. Pour en savoir plus sur les groupes de base de données, consultez [Groupes](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html) dans le *Guide du développeur de base de données Amazon Redshift*.
Vous pouvez configurer le rôle IAM d’un appelant de l’API de données de sorte que l’utilisateur de base de données spécifié dans l’appel rejoigne des groupes de base de données au moment où l’API de données se connecte à un cluster. Cette fonctionnalité n’est prise en charge que lors de la connexion à des clusters provisionnés. Elle n’est pas pris en charge lors de la connexion à des groupes de travail Redshift sans serveur. Le rôle IAM de l’appelant de l’API de données doit également autoriser l’action `redshift:JoinGroup`.
Pour configurer cela, vous devez ajouter des balises aux rôles IAM. L’administrateur du rôle IAM de l’appelant ajoute des balises avec la clé `RedshiftDbGroups` et une clé-valeur d’une liste de groupes de base de données. La valeur est une liste de noms de groupes de base de données séparés par deux points (:) d’une longueur totale maximale de 256 caractères. Les groupes de base de données doivent être préalablement définis dans la base de données connectée. Si aucun groupe spécifié n’est trouvé dans la base de données, elle est ignorée. Par exemple, pour les groupes de base de données `accounting` et `retail`, la clé-valeur est `accounting:retail`. La paire clé-valeur de balise `{"Key":"RedshiftDbGroups","Value":"accounting:retail"}` est utilisée par l’API de données pour identifier les groupes de base de données qui sont associés à l’utilisateur de base de données indiqué dans l’appel à l’API de données.
**Pour rejoindre des groupes de base de données**
1. Connectez-vous à la console IAM AWS Management Console et ouvrez-la à [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)l'adresse.
1. Dans le panneau de navigation de la console, choisissez **Roles** (Rôles), puis choisissez le nom du rôle que vous souhaitez modifier.
1. Choisissez l’onglet **Balises**, puis **Gérer les balises**.
1. Choisissez **Ajouter une balise**, puis ajoutez la clé **RedshiftDbGroups**et une valeur sous forme de liste de*database-groups-colon-separated*.
1. Sélectionnez **Enregistrer les modifications**.
Désormais, lorsqu’un principal IAM (auquel ce rôle IAM est attaché) appelle l’API de données, l’utilisateur de base de données spécifié rejoint les groupes de base de données spécifiés dans le rôle IAM.
Pour plus d’informations sur la procédure d’attachement d’une balise à un principal, y compris les rôles IAM et les utilisateurs IAM, consultez [Étiquetage des ressources IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) dans le *Guide de l’utilisateur IAM*.
# Utilisation de l’API de données avec la propagation d’identité de confiance
En tant qu'administrateur de compte Amazon Redshift, vous pouvez intégrer votre cluster ou groupe de travail Amazon Redshift, ce qui permet de gérer l'accès de votre personnel à Amazon Redshift AWS IAM Identity Center grâce à l'authentification unique. Pour de plus amples informations, veuillez consulter [Configuration de l'intégration d' AWS IAM Identity Center à Amazon Redshift](redshift-iam-access-control-idp-connect-console.md). L'API Amazon Redshift Data permet de propager les identités des utilisateurs d'IAM Identity Center à un cluster ou à un groupe de travail Amazon Redshift, ainsi qu'à d'autres services, tels que le bas de la chaîne. AWS Lake Formation Vous pouvez configurer et effectuer des requêtes à l'aide de l'API de données en suivant les étapes décrites dans [Access AWS Services de manière programmatique à l'aide d'une propagation d'identité sécurisée](https://aws.amazon.com/blogs//security/access-aws-services-programmatically-using-trusted-identity-propagation/).
Lorsque vous appelez l’API de données à l’aide d’une identité d’utilisateur IAM Identity Center à partir d’une session de rôle IAM à identité améliorée, vous ne pouvez accéder à l’instruction et au résultat de l’instruction qui en résultent qu’en utilisant le même utilisateur IAM Identity Center. Par exemple, la AWS CLI commande suivante appelle l'`execute-statement`opération pour exécuter une commande SQL avec une propagation d'identité sécurisée.
```
aws redshift-data execute-statement
--sql "select current_user;"
--cluster-id mycluster
--database dev
```
La AWS CLI commande suivante appelle l'`batch-execute-statement`opération pour exécuter deux commandes SQL.
```
aws redshift-data batch-execute-statement
--sqls "select current_user;" "select current_date;"
--cluster-id mycluster
--database dev
```
Pour accéder aux instructions avec `cancel-statement`, `describe-statement`, `get-statement-result` et `get-statement-result-v2` soumises par le biais de sessions de rôle IAM à identité améliorée, l’utilisateur IAM Identity Center et le rôle IAM doivent correspondre aux informations d’identification utilisées pour exécuter `execute-statment` ou `batch-execute-statement`. Par exemple, la AWS CLI commande suivante permet d'obtenir les résultats d'une instruction SQL.
```
aws redshift-data get-statement-result
--id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
Pour répertorier les instructions, un paramètre `cluster-identifier` ou `workgroup-name` doit être fourni pour garantir que l’utilisateur de l’IAM Identity Center n’a accès qu’aux applications Amazon Redshift IAM Identity Center auxquelles il est affecté. Par exemple, la AWS CLI commande suivante répertorie les instructions relatives à un cluster spécifique.
```
aws redshift-data list-statements
--cluster-identifier mycluster
```
Vous pouvez également appeler les opérations de l’API de données qui accèdent aux objets de base de données d’un cluster ou d’un groupe de travail à l’aide d’une propagation d’identité fiable. Cela inclut les opérations `list-databases`, `list-schemas`, `list-tables` et `describe-table`.
Les appels d’API effectués par l’utilisateur de l’IAM Identity Center peuvent être suivis dans AWS CloudTrail. Une `onBehalfOf` section de l' CloudTrail événement indique l'identifiant utilisateur du centre d'identité IAM et l'ARN du magasin d'identités. L'exemple suivant montre un extrait d'un CloudTrail événement montrant la `onBehalfOf` section portant l'ID utilisateur IAM Identity Center de `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111` et l'ARN du magasin d'identités de. `arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2`
```
{
"eventVersion":"1.10",
"userIdentity":{
"type":"AssumedRole",
...
},
"onBehalfOf":{
"userId":"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"identityStoreArn":"arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2"
}
},
"eventTime":"2025-01-13T04:46:27Z",
"eventSource":"redshift-data.amazonaws.com",
"eventName":"ExecuteStatement",
"awsRegion":"us-east-1"
}
```
Vous pouvez exécuter la commande SQL suivante pour vérifier la requête soumise par l’utilisateur IAM Identity Center. Dans cet exemple, l’e-mail enregistré dans Identity Center est `username@example.com`.
```
SELECT
h.query_id,
h.database_name,
h.status,
h.query_text,
u.usename,
h.start_time,
h.end_time
FROM
sys_query_history h
LEFT JOIN
pg_user u
ON
h.user_id = u.usesysid
where u.usename='awsidc:username@example.com'
ORDER BY
h.start_time DESC;
```
# Appel à l’API de données
Vous pouvez appeler l'API Data ou le AWS CLI pour exécuter des instructions SQL sur votre cluster ou votre groupe de travail sans serveur. Les principales opérations pour exécuter des instructions SQL sont [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html) et [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html) dans la *Référence de l’API de données Amazon Redshift*. L'API Data prend en charge les langages de programmation pris en charge par le AWS SDK. Pour plus d’informations sur ces derniers, consultez [Outils pour créer sur AWS](https://aws.amazon.com/tools/).
Pour voir des exemples de code relatifs à l'appel de l'API de données, consultez [Getting Started with Redshift Data API](https://github.com/aws-samples/getting-started-with-amazon-redshift-data-api#getting-started-with-redshift-data-api) dans. *GitHub* Ce référentiel contient des exemples d'utilisation AWS Lambda pour accéder aux données Amazon Redshift depuis Amazon EC2 et Amazon AWS Glue Data Catalog Runtime. SageMaker Les langages de programmation incluent Python, Go, Java et Javascript.
Vous pouvez appeler l’API de données avec la AWS CLI.
Les exemples suivants utilisent le AWS CLI pour appeler l'API Data. Pour exécuter les exemples, modifiez les valeurs des paramètres de manière à les adapter à votre environnement. Dans de nombreux exemples, un `cluster-identifier` est fourni pour être exécutée sur un cluster. Lorsque vous exécutez une opération sur un groupe de travail sans serveur, vous fournissez un `workgroup-name` à la place. Ces exemples illustrent quelques-unes des opérations de l’API de données. Pour plus d’informations, consultez la *référence des commandes de l’AWS CLI *.
Les commandes des exemples suivants ont été scindées et formatées pour être plus lisibles. Tous les paramètres et réponses ne sont pas présentés dans tous les exemples. Pour la définition API de la syntaxe complète de la demande, des paramètres de demande, de la syntaxe de réponse et des éléments de réponse, consultez la [Référence de l’API de données Amazon Redshift](https://docs.aws.amazon.com/redshift-data/latest/APIReference/).
# Transmission d’instructions SQL à un entrepôt de données Amazon Redshift
Les exemples présentés dans cette page présentent différentes manières de transmettre une instruction SQL à votre entrepôt de données.
## Exécuter une instruction SQL
Pour exécuter une instruction SQL, utilisez la `aws redshift-data execute-statement` AWS CLI commande.
La AWS CLI commande suivante exécute une instruction SQL sur un cluster et renvoie un identifiant pour récupérer les résultats. Cet exemple utilise la méthode d’authentification AWS Secrets Manager .
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
```
Voici un exemple de réponse.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
La AWS CLI commande suivante exécute une instruction SQL sur un cluster et renvoie un identifiant pour récupérer les résultats. Cet exemple utilise la méthode d’authentification par informations d’identification temporaires.
```
aws redshift-data execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sql "select * from stl_query limit 1"
```
Voici un exemple de réponse.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
La AWS CLI commande suivante exécute une instruction SQL sur un groupe de travail sans serveur et renvoie un identifiant pour récupérer les résultats. Cet exemple utilise la méthode d’authentification par informations d’identification temporaires.
```
aws redshift-data execute-statement
--database dev
--workgroup-name myworkgroup
--sql "select 1;"
```
Voici un exemple de réponse.
```
{
"CreatedAt": "2022-02-11T06:25:28.748000+00:00",
"Database": "dev",
"DbUser": "IAMR:RoleName",
"Id": "89dd91f5-2d43-43d3-8461-f33aa093c41e",
"WorkgroupName": "myworkgroup"
}
```
La AWS CLI commande suivante exécute une instruction SQL sur un cluster et renvoie un identifiant pour récupérer les résultats. Cet exemple utilise la méthode d’authentification AWS Secrets Manager et un jeton d’idempotence.
```
aws redshift-data execute-statement
--secret-arn 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
```
Voici un exemple de réponse.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
## Exécuter une instruction SQL avec des paramètres
Pour exécuter une instruction SQL, utilisez la `aws redshift-data execute-statement` AWS CLI commande.
La AWS CLI commande suivante exécute une instruction SQL sur un cluster et renvoie un identifiant pour récupérer les résultats. Cet exemple utilise la méthode d’authentification AWS Secrets Manager . Le texte SQL a un paramètre nommé `distance`. Dans ce cas, la distance utilisée dans le prédicat est `5`. Dans une instruction SELECT, les paramètres nommés pour les noms de colonnes ne peuvent être utilisés que dans le prédicat. Les valeurs des paramètres nommés pour l’instruction SQL sont spécifiées dans l’option `parameters`.
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "SELECT ratecode FROM demo_table WHERE trip_distance > :distance"
--parameters "[{\"name\": \"distance\", \"value\": \"5\"}]"
--database dev
```
Voici un exemple de réponse.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
L’exemple de requête suivant utilise la table `EVENT` de l’exemple de base de données. Pour plus d’informations, consultez [Table EVENT](https://docs.aws.amazon.com/redshift/latest/dg/r_eventtable.html) dans le *Manuel du développeur de bases de données Amazon Redshift*.
Si la table `EVENT` n’existe pas encore dans votre base de données, vous pouvez en créer une à l’aide de l’API de données comme suit :
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "create table event( eventid integer not null distkey,
venueid smallint not null,
catid smallint not null,
dateid smallint not null sortkey,
eventname varchar(200),
starttime timestamp)"
```
L’instruction suivante insère une ligne dans la table `EVENT`.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "insert into event values(:eventid, :venueid::smallint, :catid, :dateid, :eventname, :starttime)"
--parameters "[{\"name\": \"eventid\", \"value\": \"1\"}, {\"name\": \"venueid\", \"value\": \"1\"},
{\"name\": \"catid\", \"value\": \"1\"},
{\"name\": \"dateid\", \"value\": \"1\"},
{\"name\": \"eventname\", \"value\": \"event 1\"},
{\"name\": \"starttime\", \"value\": \"2022-02-22\"}]"
```
L’instruction suivante insère une deuxième ligne dans la table `EVENT`. Cet exemple illustre ce scénario :
+ Le paramètre nommé `id` est utilisé quatre fois dans le texte SQL.
+ La conversion de type implicite est appliquée automatiquement lors de l’insertion d’un paramètre `starttime`.
+ La colonne `venueid` est convertie en type de données SMALLINT.
+ Les chaînes de caractères qui représentent le type de données DATE sont implicitement converties en type de données TIMESTAMP.
+ Les commentaires peuvent être utilisés dans le texte SQL.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "insert into event values(:id, :id::smallint, :id, :id, :eventname, :starttime) /*this is comment, and it won't apply parameterization for :id, :eventname or :starttime here*/"
--parameters "[{\"name\": \"eventname\", \"value\": \"event 2\"},
{\"name\": \"starttime\", \"value\": \"2022-02-22\"},
{\"name\": \"id\", \"value\": \"2\"}]"
```
Voici les deux lignes insérées :
```
eventid | venueid | catid | dateid | eventname | starttime
---------+---------+-------+--------+-----------+---------------------
1 | 1 | 1 | 1 | event 1 | 2022-02-22 00:00:00
2 | 2 | 2 | 2 | event 2 | 2022-02-22 00:00:00
```
La commande suivante utilise un paramètre nommé dans une clause WHERE pour récupérer la ligne où `eventid` est `1`.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "select * from event where eventid=:id"
--parameters "[{\"name\": \"id\", \"value\": \"1\"}]"
```
Exécutez l’instruction suivante pour obtenir les résultats SQL de l’instruction SQL précédente :
```
aws redshift-data get-statement-result --id 7529ad05-b905-4d71-9ec6-8b333836eb5a
```
Fournit les résultats suivants :
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 1
},
{
"longValue": 1
},
{
"longValue": 1
},
{
"stringValue": "event 1"
},
{
"stringValue": "2022-02-22 00:00:00.0"
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "eventid",
"length": 0,
"name": "eventid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "venueid",
"length": 0,
"name": "venueid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "catid",
"length": 0,
"name": "catid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "dateid",
"length": 0,
"name": "dateid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "eventname",
"length": 0,
"name": "eventname",
"nullable": 1,
"precision": 200,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "varchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "starttime",
"length": 0,
"name": "starttime",
"nullable": 1,
"precision": 29,
"scale": 6,
"schemaName": "public",
"tableName": "event",
"typeName": "timestamp"
}
],
"TotalNumRows": 1
}
```
## Exécuter plusieurs instructions SQL
Pour exécuter plusieurs instructions SQL avec une seule commande, utilisez la `aws redshift-data batch-execute-statement` AWS CLI commande.
La AWS CLI commande suivante exécute trois instructions SQL sur un cluster et renvoie un identifiant pour récupérer les résultats. Cet exemple utilise la méthode d’authentification par informations d’identification temporaires.
```
aws redshift-data batch-execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sqls "set timezone to BST" "select * from mytable" "select * from another_table"
```
Voici un exemple de réponse.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
# Répertorier les métadonnées sur les instructions SQL
Pour répertorier les métadonnées relatives aux instructions SQL, utilisez la `aws redshift-data list-statements` AWS CLI commande. L’autorisation d’exécuter cette commande est basée sur les autorisations IAM de l’appelant.
La AWS CLI commande suivante répertorie les instructions SQL exécutées.
```
aws redshift-data list-statements
--status ALL
```
Voici un exemple de réponse.
```
{
"Statements": [
{
"CreatedAt": 1598306924.632,
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766",
"QueryString": "select * from stl_query limit 1",
"Status": "FINISHED",
"UpdatedAt": 1598306926.667
},
{
"CreatedAt": 1598311717.437,
"Id": "e0ebd578-58b3-46cc-8e52-8163fd7e01aa",
"QueryString": "select * from stl_query limit 1",
"Status": "FAILED",
"UpdatedAt": 1598311719.008
},
{
"CreatedAt": 1598313683.65,
"Id": "c361d4f7-8c53-4343-8c45-6b2b1166330c",
"QueryString": "select * from stl_query limit 1",
"Status": "ABORTED",
"UpdatedAt": 1598313685.495
},
{
"CreatedAt": 1598306653.333,
"Id": "a512b7bd-98c7-45d5-985b-a715f3cfde7f",
"QueryString": "select 1",
"Status": "FINISHED",
"UpdatedAt": 1598306653.992
}
]
}
```
# Décrire des métadonnées à propos d’une instruction SQL
Pour obtenir la description des métadonnées d'une instruction SQL, utilisez la `aws redshift-data describe-statement` AWS CLI commande. L’autorisation d’exécuter cette commande est basée sur les autorisations IAM de l’appelant.
La AWS CLI commande suivante décrit une instruction SQL.
```
aws redshift-data describe-statement
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
Voici un exemple de réponse.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Duration": 1095981511,
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766",
"QueryString": "select * from stl_query limit 1",
"RedshiftPid": 20859,
"RedshiftQueryId": 48879,
"ResultRows": 1,
"ResultSize": 4489,
"Status": "FINISHED",
"UpdatedAt": 1598306926.667
}
```
Voici un exemple de réponse de `describe-statement` après l’exécution d’une commande `batch-execute-statement` avec plusieurs instructions SQL.
```
{
"ClusterIdentifier": "mayo",
"CreatedAt": 1623979777.126,
"Duration": 6591877,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652",
"RedshiftPid": 31459,
"RedshiftQueryId": 0,
"ResultRows": 2,
"ResultSize": 22,
"Status": "FINISHED",
"SubStatements": [
{
"CreatedAt": 1623979777.274,
"Duration": 3396637,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:1",
"QueryString": "select 1;",
"RedshiftQueryId": -1,
"ResultRows": 1,
"ResultSize": 11,
"Status": "FINISHED",
"UpdatedAt": 1623979777.903
},
{
"CreatedAt": 1623979777.274,
"Duration": 3195240,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2",
"QueryString": "select 2;",
"RedshiftQueryId": -1,
"ResultRows": 1,
"ResultSize": 11,
"Status": "FINISHED",
"UpdatedAt": 1623979778.076
}
],
"UpdatedAt": 1623979778.183
}
```
# Récupérer les résultats d’une instruction SQL
Pour récupérer le résultat d'une instruction SQL exécutée, utilisez la `redshift-data get-statement-result-v2` AWS CLI commande `redshift-data get-statement-result` or. Les résultats de `get-statement-result` sont au format JSON. Les résultats de `get-statement-result-v2` sont au format CSV. Vous pouvez spécifier un `Id` que vous recevez en réponse à `execute-statement` ou `batch-execute-statement`. La valeur `Id` d’une instruction SQL exécutée par `batch-execute-statement` peut être récupéré dans le résultat de `describe-statement` et son suffixe est composé de deux points suivis d’un numéro de séquence tel que `b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2`. Si vous exécutez plusieurs instructions SQL avec `batch-execute-statement`, chaque instruction SQL a une valeur `Id` comme indiqué dans `describe-statement`. L’autorisation d’exécuter cette commande est basée sur les autorisations IAM de l’appelant.
L’instruction suivante renvoie le résultat d’une instruction SQL exécutée par `execute-statement` laissant le `ResultFormat` par défaut sur `JSON`. Pour récupérer les résultats, appelez l’opération `get-statement-result`.
```
aws redshift-data get-statement-result
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
L’instruction suivante renvoie le résultat de la deuxième instruction SQL exécutée par `batch-execute-statement`.
```
aws redshift-data get-statement-result
--id b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2
```
Voici un exemple de réponse à un appel de `get-statement-result` où le résultat SQL est renvoyé au format JSON dans la clé `Records` de la réponse.
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "userid",
"length": 0,
"name": "userid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "query",
"length": 0,
"name": "query",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "label",
"length": 0,
"name": "label",
"nullable": 0,
"precision": 320,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "xid",
"length": 0,
"name": "xid",
"nullable": 0,
"precision": 19,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int8"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "pid",
"length": 0,
"name": "pid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "database",
"length": 0,
"name": "database",
"nullable": 0,
"precision": 32,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "querytxt",
"length": 0,
"name": "querytxt",
"nullable": 0,
"precision": 4000,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "starttime",
"length": 0,
"name": "starttime",
"nullable": 0,
"precision": 29,
"scale": 6,
"schemaName": "",
"tableName": "stll_query",
"typeName": "timestamp"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "endtime",
"length": 0,
"name": "endtime",
"nullable": 0,
"precision": 29,
"scale": 6,
"schemaName": "",
"tableName": "stll_query",
"type": 93,
"typeName": "timestamp"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "aborted",
"length": 0,
"name": "aborted",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "insert_pristine",
"length": 0,
"name": "insert_pristine",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "concurrency_scaling_status",
"length": 0,
"name": "concurrency_scaling_status",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
}
],
"Records": [
[
{
"longValue": 1
},
{
"longValue": 3
},
{
"stringValue": "health"
},
{
"longValue": 1023
},
{
"longValue": 15279
},
{
"stringValue": "dev"
},
{
"stringValue": "select system_status from stv_gui_status;"
},
{
"stringValue": "2020-08-21 17:33:51.88712"
},
{
"stringValue": "2020-08-21 17:33:52.974306"
},
{
"longValue": 0
},
{
"longValue": 0
},
{
"longValue": 6
}
]
],
"TotalNumRows": 1
}
```
L’exemple suivant montre une instruction SQL exécutée par `execute-statement` pour renvoyer des résultats au format JSON. La table `testingtable` comporte trois colonnes entières (col1, col2, col3) et trois lignes contenant des valeurs (1, 2, 3), (4, 5, 6) et (7, 8, 9).
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format JSON
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
Voici un exemple de réponse à un appel de `get-statement-result` où le résultat SQL est renvoyé au format JSON dans la clé `Records` de la réponse.
```
aws redshift-data get-statement-result
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 2
},
{
"longValue": 3
}
],
[
{
"longValue": 4
},
{
"longValue": 5
},
{
"longValue": 6
}
],
[
{
"longValue": 7
},
{
"longValue": 8
},
{
"longValue": 9
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3
}
```
L’exemple suivant montre une instruction SQL exécutée par `execute-statement` pour renvoyer des résultats au format CSV. La table `testingtable` comporte trois colonnes entières (col1, col2, col3) et trois lignes contenant des valeurs (1, 2, 3), (4, 5, 6) et (7, 8, 9).
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format CSV
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
Voici un exemple de réponse à un appel de `get-statement-result-v2` où le résultat SQL est renvoyé au format CSV dans la clé `Records` de la réponse. Les lignes sont séparées par un retour du chariot et par une nouvelle ligne (\$1r\$1n). La première ligne renvoyée dans `Records` correspond aux en-têtes de colonne. Les résultats renvoyés au format CSV sont renvoyés dans un format de 1 Mo, chaque bloc pouvant stocker un nombre quelconque de lignes allant jusqu’à 1 Mo.
```
aws redshift-data get-statement-result-v2
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
{
"CSVRecords": "col1,col2,col3\r\n1,2,3\r\n4,5,6\r\n7,8,9\r\n"
}
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3,
"ResultFormat": "csv"
}
```
# Décrire une table
Pour obtenir des métadonnées décrivant une table, utilisez la `aws redshift-data describe-table` AWS CLI commande.
La AWS CLI commande suivante exécute une instruction SQL sur un cluster et renvoie des métadonnées décrivant une table. Cet exemple utilise la méthode AWS Secrets Manager d'authentification.
```
aws redshift-data describe-table
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
```
Voici un exemple de réponse.
```
{
"ColumnList": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
}
]
}
```
La AWS CLI commande suivante exécute une instruction SQL sur un cluster qui décrit une table. Cet exemple utilise la méthode d’authentification par informations d’identification temporaires.
```
aws redshift-data describe-table
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
```
Voici un exemple de réponse.
```
{
"ColumnList": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "sub_feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "sub_feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "is_supported",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "is_verified_by",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "comments",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
}
]
}
```
# Répertorier les bases de données dans un cluster
Pour répertorier les bases de données d'un cluster, utilisez la `aws redshift-data list-databases` AWS CLI commande.
La AWS CLI commande suivante exécute une instruction SQL sur un cluster pour répertorier les bases de données. Cet exemple utilise la méthode AWS Secrets Manager d'authentification.
```
aws redshift-data list-databases
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
Voici un exemple de réponse.
```
{
"Databases": [
"dev"
]
}
```
La AWS CLI commande suivante exécute une instruction SQL sur un cluster pour répertorier les bases de données. Cet exemple utilise la méthode d’authentification par informations d’identification temporaires.
```
aws redshift-data list-databases
--db-user myuser
--cluster-identifier mycluster-test
--database dev
```
Voici un exemple de réponse.
```
{
"Databases": [
"dev"
]
}
```
# Répertorier les schémas dans une base de données
Pour répertorier les schémas d'une base de données, utilisez la `aws redshift-data list-schemas` AWS CLI commande.
La AWS CLI commande suivante exécute une instruction SQL sur un cluster pour répertorier les schémas d'une base de données. Cet exemple utilise la méthode AWS Secrets Manager d'authentification.
```
aws redshift-data list-schemas
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
Voici un exemple de réponse.
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
La AWS CLI commande suivante exécute une instruction SQL sur un cluster pour répertorier les schémas d'une base de données. Cet exemple utilise la méthode d’authentification par informations d’identification temporaires.
```
aws redshift-data list-schemas
--db-user mysuser
--cluster-identifier mycluster-test
--database dev
```
Voici un exemple de réponse.
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
# Répertorier les tables dans une base de données
Pour répertorier les tables d'une base de données, utilisez la `aws redshift-data list-tables` AWS CLI commande.
La AWS CLI commande suivante exécute une instruction SQL sur un cluster pour répertorier les tables d'une base de données. Cet exemple utilise la méthode AWS Secrets Manager d'authentification.
```
aws redshift-data list-tables
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
Voici un exemple de réponse.
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
}
```
La AWS CLI commande suivante exécute une instruction SQL sur un cluster pour répertorier les tables d'une base de données. Cet exemple utilise la méthode d’authentification par informations d’identification temporaires.
```
aws redshift-data list-tables
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
Voici un exemple de réponse.
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
]
}
```
# Résolution des problèmes liés à l’API de données Amazon Redshift
Utilisez les sections suivantes, dont le titre correspond aux messages d’erreur courants, pour vous aider à résoudre les problèmes que vous rencontrez avec l’API de données.
**Topics**
+ [Packet for query is too large](#data-api-troubleshooting-packet-too-large)
+ [Database Response Exceeded Size Limit](#data-api-troubleshooting-response-size-too-large)
## Packet for query is too large
Si vous obtenez une erreur indiquant que le paquet pour une requête est trop grand, cela signifie généralement que l’ensemble de résultats renvoyé pour une ligne est trop grand. La taille de l’API de données ne doit pas dépasser 64 Ko par ligne dans le jeu de résultat renvoyé par la base de données.
Pour résoudre ce problème, assurez-vous que la taille de chaque ligne d’un jeu de résultat est inférieure ou égale à 64 Ko.
## Database Response Exceeded Size Limit
Si vous obtenez une erreur indiquant que la réponse de la base de données a dépassé la limite de taille, cela signifie généralement que la taille de l’ensemble de résultats renvoyé par la base de données était trop importante. La limite de l'API de données est de 500 Mo dans le jeu de résultats renvoyé par la base de données.
Pour résoudre ce problème, assurez-vous que les appels à l'API Data renvoient 500 Mo de données ou moins. Si vous devez renvoyer plus de 500 Mo, vous pouvez exécuter plusieurs appels d'instruction avec la `LIMIT` clause contenue dans votre requête.
# Planification des opérations de l'API Amazon Redshift Data avec Amazon EventBridge
Vous pouvez créer des règles qui correspondent à des événements sélectionnés et les acheminent vers des cibles pour qu’elles prennent des mesures. Vous pouvez également utiliser des règles pour effectuer des actions sur une planification prédéterminée. Pour plus d'informations, consultez le [guide de EventBridge l'utilisateur Amazon](https://docs.aws.amazon.com/eventbridge/latest/userguide/).
Pour planifier les opérations de l'API de données avec EventBridge, le rôle IAM associé doit faire confiance au principal pour les CloudWatch événements (events.amazonaws.com). Ce rôle doit être assorti de l’équivalent de la politique gérée `AmazonEventBridgeFullAccess`. Il doit également disposer des autorisations de la politique `AmazonRedshiftDataFullAccess` qui sont gérées par l’API de données. Vous pouvez créer un rôle IAM avec ces autorisations sur la console IAM. Lorsque vous créez un rôle sur la console IAM, choisissez l'entité de confiance du AWS service pour les CloudWatch événements. Spécifiez le rôle IAM dans la valeur `RoleArn` JSON de la EventBridge cible. Pour plus d'informations sur la création d'un rôle IAM, consultez la section [Création d'un rôle pour un AWS service (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console) dans le guide de l'*utilisateur IAM*.
La `name` règle que vous créez dans Amazon EventBridge doit correspondre `StatementName` à celle du`RedshiftDataParameters`.
Les exemples suivants montrent des variantes de création de EventBridge règles avec une ou plusieurs instructions SQL et avec un cluster Amazon Redshift ou un groupe de travail Amazon Redshift Serverless comme entrepôt de données.
## Appel à l’aide d’une seule instruction SQL et d’un cluster
L'exemple suivant utilise le AWS CLI pour créer une EventBridge règle qui est utilisée pour exécuter une instruction SQL sur un cluster Amazon Redshift.
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
Ensuite, une EventBridge cible est créée pour s'exécuter selon le calendrier spécifié dans la règle.
```
aws events put-targets
--cli-input-json file://data.json
```
Le fichier d’entrée data.json se présente comme suit. La clé JSON `Sql` indique qu’il y a une seule instruction SQL. La valeur JSON `Arn` contient un identifiant de cluster. La valeur JSON `RoleArn` contient le rôle IAM utilisé pour exécuter le SQL comme décrit précédemment.
```
{
"Rule": "test-redshift-cluster-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"DbUser": "root",
"Sql": "select 1;",
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## Appel à l’aide d’une seule instruction SQL et d’un groupe de travail
L'exemple suivant utilise le AWS CLI pour créer une EventBridge règle qui est utilisée pour exécuter une instruction SQL sur un groupe de travail Amazon Redshift Serverless.
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
Ensuite, une EventBridge cible est créée pour s'exécuter selon le calendrier spécifié dans la règle.
```
aws events put-targets
--cli-input-json file://data.json
```
Le fichier d’entrée data.json se présente comme suit. La clé JSON `Sql` indique qu’il y a une seule instruction SQL. La valeur JSON `Arn` contient un nom de groupe de travail. La valeur JSON `RoleArn` contient le rôle IAM utilisé pour exécuter le SQL comme décrit précédemment.
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sql": "select 1;",
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
## Appel à l’aide de plusieurs instructions SQL et d’un cluster
L'exemple suivant utilise le AWS CLI pour créer une EventBridge règle qui est utilisée pour exécuter plusieurs instructions SQL sur un cluster Amazon Redshift.
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
Ensuite, une EventBridge cible est créée pour s'exécuter selon le calendrier spécifié dans la règle.
```
aws events put-targets
--cli-input-json file://data.json
```
Le fichier d’entrée data.json se présente comme suit. La clé JSON `Sqls` indique qu’il existe plusieurs instructions SQL. La valeur JSON `Arn` contient un identifiant de cluster. La valeur JSON `RoleArn` contient le rôle IAM utilisé pour exécuter le SQL comme décrit précédemment.
```
{
"Rule": "test-redshift-cluster-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## Appel à l’aide de plusieurs instructions SQL et d’un groupe de travail
L'exemple suivant utilise le AWS CLI pour créer une EventBridge règle qui est utilisée pour exécuter plusieurs instructions SQL sur un groupe de travail Amazon Redshift Serverless.
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
Ensuite, une EventBridge cible est créée pour s'exécuter selon le calendrier spécifié dans la règle.
```
aws events put-targets
--cli-input-json file://data.json
```
Le fichier d’entrée data.json se présente comme suit. La clé JSON `Sqls` indique qu’il existe plusieurs instructions SQL. La valeur JSON `Arn` contient un nom de groupe de travail. La valeur JSON `RoleArn` contient le rôle IAM utilisé pour exécuter le SQL comme décrit précédemment.
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
# Surveillance de l’API de données
La surveillance joue un rôle important dans le maintien de la fiabilité, de la disponibilité et des performances de l'API de données et de vos autres AWS solutions. AWS fournit les outils de surveillance suivants pour surveiller l'API de données, signaler un problème et prendre des mesures automatiques le cas échéant :
+ Amazon EventBridge peut être utilisé pour automatiser vos AWS services et répondre automatiquement aux événements du système, tels que les problèmes de disponibilité des applications ou les modifications des ressources. Les événements liés AWS aux services sont diffusés EventBridge en temps quasi réel. Vous pouvez écrire des règles simples pour préciser les événements qui vous intéressent et les actions automatisées à effectuer quand un événement correspond à une règle. Pour plus d'informations, consultez le [guide de EventBridge l'utilisateur Amazon](https://docs.aws.amazon.com/eventbridge/latest/userguide/).
+ AWS CloudTrail capture les appels d'API et les événements associés effectués par ou pour le compte de votre AWS compte et envoie les fichiers journaux dans un compartiment Amazon S3 que vous spécifiez. Vous pouvez identifier les utilisateurs et les comptes appelés AWS, l'adresse IP source à partir de laquelle les appels ont été effectués et la date des appels. Pour en savoir plus sur la façon dont Amazon Redshift est intégré AWS CloudTrail, consultez [Logging](https://docs.aws.amazon.com/redshift/latest/mgmt/logging-with-cloudtrail.html) with. CloudTrail Pour plus d'informations CloudTrail, consultez le [guide de AWS CloudTrail l'utilisateur](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
**Topics**
+ [Surveillance des événements pour l'API Amazon Redshift Data sur Amazon EventBridge](data-api-monitoring-events.md)
# Surveillance des événements pour l'API Amazon Redshift Data sur Amazon EventBridge
Vous pouvez surveiller les événements de l'API de données dans EventBridge, qui fournit un flux de données en temps réel à partir de vos propres applications, applications software-as-a-service (SaaS) et AWS services. EventBridge achemine ces données vers des cibles telles qu' AWS Lambda Amazon SNS. Ces événements sont les mêmes que ceux qui apparaissent dans CloudWatch Events, qui fournit un flux quasi en temps réel d'événements système décrivant les modifications apportées aux AWS ressources. Les événements sont envoyés au compte qui contient la base de données Amazon Redshift. Par exemple, si vous assumez un rôle dans un autre compte, les événements sont envoyés à ce compte. Pour plus d'informations, consultez les [ EventBridge événements Amazon](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) dans le *guide de EventBridge l'utilisateur Amazon.* .
Les événements de l’API de données sont envoyés lorsque l’opération de l’API `ExecuteStatement` ou `BatchExecuteStatement` attribue à l’option `WithEvent` la valeur `true`. Le champ `state` de l’événement peut comporter l’une des valeurs suivantes :
+ ABORTED (Abandonné) – L’exécution de la requête a été arrêtée par l’utilisateur.
+ FAILED – L’exécution de la requête a échoué.
+ FINISHED – L’exécution de la requête est terminée.
Les événements sont fournis sur la base de la garantie. Pour plus d'informations, consultez la section [Événements liés AWS aux services](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) dans le *guide de EventBridge l'utilisateur Amazon*.
## Exemple pour l’événement terminé (FINISHED) de l’API de données
L’exemple suivant montre un événement pour l’API de données lorsque l’opération d’API `ExecuteStatement` se termine. Dans cet exemple, une instruction nommée `test.testtable` a terminé son exécution.
```
{
"version": "0",
"id": "18e7079c-dd4b-dd64-caf9-e2a31640dab0",
"detail-type": "Redshift Data Statement Status Change",
"source": "aws.redshift-data",
"account": "123456789012",
"time": "2020-10-01T21:14:26Z",
"region": "us-east-1",
"resources": [
"arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster-1"
],
"detail": {
"principal": "arn:aws:iam::123456789012:user/myuser",
"statementName": "test.testtable",
"statementId": "dd2e1ec9-2ee3-49a0-819f-905fa7d75a4a",
"redshiftQueryId": -1,
"state": "FINISHED",
"rows": 1,
"expireAt": 1601673265
}
}
```
# Utilisation AWS KMS avec l'API de données Amazon Redshift
Lorsque vous chiffrez votre cluster Amazon Redshift ou votre groupe de travail Redshift Serverless avec une clé gérée par le client, l'API Amazon Redshift Data utilise cette même clé gérée par le client pour stocker et chiffrer vos requêtes et vos résultats.
L'API Data chiffre vos données par défaut pour protéger les informations sensibles, telles que le texte des requêtes et les résultats des requêtes. Il utilise des clés de AWS KMS chiffrement détenues par lui AWS pour cette protection.
Le chiffrement par défaut des données au repos réduit la charge opérationnelle et la complexité lorsque vous protégez des données sensibles. Cette approche vous permet de créer des applications sécurisées qui répondent aux exigences réglementaires et de conformité strictes en matière de chiffrement.
## Utilisation de subventions dans AWS KMS
L'API Data nécessite une autorisation pour utiliser votre clé gérée par le client.
Lorsque vous appelez `ExecuteStatement` ou `BatchExecuteStatement` défiez un cluster chiffré à l'aide d'une clé gérée par le client, Amazon Redshift crée une subvention en votre nom en envoyant une [https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)demande à. AWS KMS AWS KMS utilise des autorisations pour donner à l'API de données l'accès à une clé KMS de votre compte.
L'API Data nécessite l'autorisation d'utiliser votre clé gérée par le client pour les opérations suivantes :
+ Envoyez [https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html)des demandes AWS KMS à pour chiffrer les métadonnées des requêtes avec votre clé gérée par le client.
+ Envoyez [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)des demandes AWS KMS à pour générer des clés de données chiffrées par votre clé gérée par le client.
+ Envoyez [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)des demandes AWS KMS à pour déchiffrer les clés de données chiffrées afin qu'ils puissent chiffrer vos données.
Vous pouvez révoquer l'accès à l'autorisation ou supprimer l'accès d'Amazon Redshift à votre clé gérée par le client à tout moment. Dans ce cas, l'API Data ne peut plus accéder aux données chiffrées par votre clé gérée par le client, ce qui affecte les opérations qui dépendent de ces données. Par exemple, si vous essayez de récupérer les résultats d'une requête ou de suivre l'état de la requête après avoir révoqué l'autorisation, l'API Data renvoie un`AccessDeniedException`.
## Politiques clés relatives à votre clé gérée par le client
Les stratégies de clés contrôlent l’accès à votre clé gérée par le client. Chaque clé gérée par le client doit avoir exactement une stratégie de clé, qui contient des instructions qui déterminent les personnes pouvant utiliser la clé et comment elles peuvent l’utiliser. Lorsque vous créez votre clé gérée par le client, vous pouvez spécifier une stratégie de clé. Pour plus d’informations, consultez [Clés gérées par le client](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key) dans le *Guide du développeur AWS Key Management Service *.
Pour utiliser les clés gérées par le client avec l'API Data, vous devez d'abord autoriser l'accès à Amazon Redshift. Les opérations d'API suivantes doivent être autorisées dans la politique clé :
+ `kms:CreateGrant` : ajoute une attribution à une clé gérée par le client. Accorde un accès de contrôle à une AWS KMS clé spécifiée, ce qui permet d'autoriser les opérations requises par Amazon Redshift. Pour plus d'informations, consultez la section [Utilisation de subventions dans AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations).
Voici un exemple de politique clé :
```
"Statement":[
{
"Sid":"Allow access to principals authorized to use Amazon Redshift",
"Effect":"Allow",
"Principal":{
"AWS":"*"
},
"Action":[
"kms:DescribeKey",
"kms:CreateGrant"
],
"Resource":"*",
"Condition":{
"StringEquals":{
"kms:ViaService":"redshift.amazonaws.com",
"kms:CallerAccount":"111122223333"
}
}
},
{
"Sid":"AllowKeyAdministratorsAccess",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleAdminRole"
},
"Action":"kms:*",
"Resource":"*"
},
{
"Sid":"AllowKeyUseForExampleRole",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleUserRole"
},
"Action":[
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource":"*"
}
]
```
## Contexte de chiffrement des API de données
Un contexte de chiffrement est un ensemble facultatif de paires clé-valeur qui contient des informations contextuelles supplémentaires sur les données. AWS KMS utilise le contexte de chiffrement comme données authentifiées supplémentaires pour prendre en charge le chiffrement authentifié. Lorsque vous incluez un contexte de chiffrement dans une demande de chiffrement de données, AWS KMS lie le contexte de chiffrement aux données chiffrées. Pour déchiffrer les données, vous devez inclure le même contexte de chiffrement dans la demande.
L'API Data utilise les trois mêmes paires clé-valeur de contexte de chiffrement dans toutes les opérations AWS KMS cryptographiques pour les clusters provisionnés :
+ `aws:redshift:arn`— Le nom de ressource Amazon (ARN) du cluster
+ `aws:redshift:createtime`— L'horodatage auquel vous avez demandé la création du cluster
+ `serviceName` – `RedshiftDataAPI`
```
"EncryptionContextSubset": {
"aws:redshift:arn": "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster",
"aws:redshift:createtime": "20250815T0000Z",
"serviceName": "RedshiftDataAPI",
}
```
L'API Data utilise deux paires clé-valeur de contexte de chiffrement dans toutes les opérations AWS KMS cryptographiques pour les groupes de travail sans serveur :
+ `aws:redshift-serverless:arn`— Le nom de ressource Amazon (ARN) de l'espace de noms
+ `serviceName`— RedshiftData API
```
"EncryptionContextSubset": {
"aws:redshift-serverless:arn": "arn:aws:redshift-serverless:us-east-1:123456789012:namespace:12345678-1234-1234-1234-123456789012",
"serviceName": "RedshiftDataAPI"
}
```
Pour plus d'informations sur le chiffrement, [voir Présentation des détails cryptographiques de AWS KMS](https://docs.aws.amazon.com/kms/latest/cryptographic-details/intro.html). Pour plus d'informations sur Amazon Redshift et son AWS KMS intégration, consultez [Comment Amazon Redshift utilise](https://docs.aws.amazon.com/kms/latest/developerguide/services-redshift.html). AWS KMS