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 Amazon Redshift Data 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 opérations de l'API de données, consultez le manuel Amazon Redshift Data API Reference.

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

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, consultez Amazon SageMaker AI et AWS Cloud9.

Pour en savoir plus sur l'API de données, consultez Commencer à utiliser l'API de données Amazon Redshift sur 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 :

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 :

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

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

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

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

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.

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 :

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.

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

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

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

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

Exécution d'instructions SQL avec réutilisation de session lors de l'appel de l'API Amazon Redshift Data

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, l'API de données ExecuteStatement et BatchExecuteStatement les opérations ont un SessionKeepAliveSeconds paramètre facultatif. Un champ de SessionId réponse contient l'identité de la session qui peut ensuite être utilisée dans les BatchExecuteStatement opérations ExecuteStatement et opérations suivantes. Lors des appels suivants, vous pouvez en spécifier un autre SessionKeepAliveSeconds pour modifier le délai d'inactivité. Si le n'SessionKeepAliveSecondsest pas modifié, le paramètre de délai d'inactivité initial est conservé. Tenez compte des points suivants lorsque vous utilisez la réutilisation des sessions :

Pour récupérer SessionId ce qui est utilisé par les appels ExecuteStatement et les BatchExecuteStatement opérations, les appels DescribeStatement et les ListStatements opérations.

L'exemple suivant montre comment utiliser les SessionId paramètres SessionKeepAliveSeconds et 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 sur2.

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 session-keep-alive-seconds paramètre 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 BatchExecuteStatement des opérations, vous pouvez spécifier si les résultats sont au format JSON ou CSV. Si vous ne le spécifiez pas, la valeur par défaut est JSON. Pour récupérer les résultats JSON, utilisez l'GetStatementResultopération. Pour récupérer les résultats CSV, utilisez l'GetStatementResultV2opération.

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": "<token>",
   "Records": [
        [
            {
                "longValue": 1
            }
        ]
    ],
   "TotalNumRows": <number>
}

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 demande 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": "<token>",
    "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": <number>
}