AWS Athenaアクション

このページでは、ワークフロー自動化アクションカタログで利用可能なAWS Athenaアクションのリファレンスを提供します。これらのアクションを使用して、Amazon Athenaに対してSQLクエリを実行し、その実行ステータスを確認して、ワークフロー定義から直接結果を取得します。

前提条件

前提条件と認証情報のセットアップについては、AWS認証情報のセットアップをご覧ください。

クエリの実行を開始します。

アクション識別子はaws.athena.startQueryExecutionです。

Amazon Athenaに対してSQLクエリを実行し、クエリ実行IDを返します。このアクションはクエリの完了を待機しません — ステータスをポーリングするにはaws.athena.getQueryExecutionを、結果を取得するにはaws.athena.getQueryResultsを使用してください。

次の表に、このアクションの入力フィールドについて説明します。

入力	タイプ	説明	例
`region`	弦	必須。AthenaワークグループのAWSリージョン。	`us-east-2`
`queryString`	弦	必須。実行するSQLステートメント。長さ：1～262,144文字。	`"SELECT * FROM my_table LIMIT 10"`
`awsRoleArn`	弦	オプション。AWS APIコール用に引き受けるIAMロールARN。	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	弦	オプション。AWSアクセスキーID。シークレットとして渡します。	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	弦	オプション。AWSシークレットアクセスキー。シークレットとして渡します。	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	弦	オプション。STS認証用の一時的なセッショントークンです。シークレットとして渡してください。	`${{ :secrets:awsSessionToken }}`
`database`	弦	オプション。クエリを実行するAthenaデータベース。長さ：1～255文字。	`"my-database"`
`catalog`	弦	オプション。データカタログ名。長さ：1～256文字。	`"AwsDataCatalog"`
`outputLocation`	弦	オプション。クエリ結果のS3 URIです。ワークグループにデフォルトの出力場所がない場合に必須です。	`"s3://my-athena-results-bucket/path/"`
`encryptionOption`	弦	オプション。結果ファイルの暗号化。許可される値：`SSE_S3`、`SSE_KMS`、`CSE_KMS`。	`"SSE_S3"`
`kmsKey`	弦	オプション。KMSキーのARNまたはID。`encryptionOption`が`SSE_KMS`または`CSE_KMS`の場合に必須です。	`"arn:aws:kms:us-east-2:123456789012:key/abc123"`
`expectedBucketOwner`	弦	オプション。出力S3バケットを所有する必要がある12桁のAWSアカウントIDです。	`"111122223333"`
`aclS3Option`	弦	オプション。結果オブジェクトに適用される定義済みACLです。許可される値：`BUCKET_OWNER_FULL_CONTROL`。	`"BUCKET_OWNER_FULL_CONTROL"`
`workGroup`	弦	オプション。クエリを実行するAthenaワークグループ。省略した場合は`primary`がデフォルトになります。長さ：1～128文字。	`"primary"`
`clientRequestToken`	弦	オプション。再試行用のべき等性トークンです。長さ：32～128文字。	`"3f2504e0-4f89-41d3-9a0c-0305e82c3301"`
`executionParameters`	リスト	オプション。位置順に適用される、パラメーター化されたクエリのパラメーター値です。各値：1～1,024文字。	`["value1", "value2"]`
`resultReuseEnabled`	ブール値	オプション。`true`の場合、前回のクエリ結果が`resultReuseMaxAgeInMinutes`以内であれば再利用します。	`true`
`resultReuseMaxAgeInMinutes`	整数	オプション。再利用可能な結果の最大経過時間（分単位）です。範囲：0～10,080。	`60`
`selectors`	リスト	オプション。アクションの出力から特定のフィールドを抽出するためのJQセレクター。	`[{"name": "queryExecutionId", "expression": ".response.QueryExecutionId"}]`

次の表は、このアクションの出力フィールドについて説明しています。

出力	タイプ	例
`response`	オブジェクト	`{"QueryExecutionId": "ef4a125f-9e79-466d-bae5-d6d36536fbee"}`。StartQueryExecution APIリファレンスを参照してください。
`success`	ブール値	`true` または `false`
`errorMessage`	弦	`"An error occurred (InvalidRequestException) when calling the StartQueryExecution operation: ..."`

例

name: start-athena-query
description: Run a SQL query against Athena
steps:
  - name: startQuery
    type: action
    action: aws.athena.startQueryExecution
    version: '1'
    inputs:
      awsRoleArn: ${{ :secrets:awsRoleArn }}
      region: us-east-2
      queryString: "SELECT * FROM my_table LIMIT 10"
      database: "my-database"
      catalog: "AwsDataCatalog"
      outputLocation: "s3://my-athena-results-bucket/path/"
      workGroup: "primary"
      selectors:
        - name: queryExecutionId
          expression: ".response.QueryExecutionId"
    next: end

クエリ実行の取得

アクション識別子はaws.athena.getQueryExecutionです。

実行IDを使用して、単一のAthenaクエリ実行の詳細と現在のステータスを返します。これを使用して、aws.athena.startQueryExecutionによって開始されたクエリが終了状態（SUCCEEDED、FAILED、またはCANCELLED）に達するまでポーリングしてください。

次の表に、このアクションの入力フィールドについて説明します。

入力	タイプ	説明	例
`region`	弦	必須。AthenaワークグループのAWSリージョン。	`us-east-2`
`queryExecutionId`	弦	必須。`aws.athena.startQueryExecution`によって返されたクエリ実行のUUID。長さ：1～128文字。	`"ef4a125f-9e79-466d-bae5-d6d36536fbee"`
`awsRoleArn`	弦	オプション。AWS APIコール用に引き受けるIAMロールARN。	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	弦	オプション。AWSアクセスキーID。シークレットとして渡します。	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	弦	オプション。AWSシークレットアクセスキー。シークレットとして渡します。	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	弦	オプション。STS認証用の一時的なセッショントークンです。シークレットとして渡してください。	`${{ :secrets:awsSessionToken }}`
`selectors`	リスト	オプション。アクションの出力から特定のフィールドを抽出するためのJQセレクター。	`[{"name": "state", "expression": ".response.QueryExecution.Status.State"}]`

次の表は、このアクションの出力フィールドについて説明しています。

出力	タイプ	例
`response`	オブジェクト	`Status`（`State`、`StateChangeReason`、タイムスタンプ、`AthenaError`）を含む`QueryExecution`、`Statistics`、`ResultConfiguration`、`QueryExecutionContext`、`WorkGroup`、および`EngineVersion`が含まれています。「GetQueryExecution APIリファレンス」を参照してください。
`success`	ブール値	`true` または `false`
`errorMessage`	弦	`"An error occurred (InvalidRequestException) when calling the GetQueryExecution operation: ..."`

例

name: get-athena-query-execution
description: Check the status of an Athena query execution
steps:
  - name: getExecution
    type: action
    action: aws.athena.getQueryExecution
    version: '1'
    inputs:
      awsRoleArn: ${{ :secrets:awsRoleArn }}
      region: us-east-2
      queryExecutionId: "ef4a125f-9e79-466d-bae5-d6d36536fbee"
      selectors:
        - name: state
          expression: ".response.QueryExecution.Status.State"
        - name: stateChangeReason
          expression: ".response.QueryExecution.Status.StateChangeReason"
    next: end

クエリ結果を取得

アクション識別子はaws.athena.getQueryResultsです。

完了したAthenaクエリ実行の行および列のメタデータを返します。結果はページ分割されます — レスポンスにNextTokenが含まれる場合、次のページを取得するための次回の呼び出し時にnextTokenとして渡してください。ResultSet.Rowsの最初の行は常にヘッダー行（列名）です。

次の表に、このアクションの入力フィールドについて説明します。

入力	タイプ	説明	例
`region`	弦	必須。AthenaワークグループのAWSリージョン。	`us-east-2`
`queryExecutionId`	弦	必須。完了したクエリ実行のUUID。長さ：1～128文字。	`"8d0105c1-30b5-4b8f-a23e-a1b60047c43f"`
`awsRoleArn`	弦	オプション。AWS APIコール用に引き受けるIAMロールARN。	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	弦	オプション。AWSアクセスキーID。シークレットとして渡します。	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	弦	オプション。AWSシークレットアクセスキー。シークレットとして渡します。	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	弦	オプション。STS認証用の一時的なセッショントークンです。シークレットとして渡してください。	`${{ :secrets:awsSessionToken }}`
`nextToken`	弦	オプション。以前に切り捨てられたレスポンスからのページネーショントークンです。最初のページから開始する場合は、省略してください。長さ：1～1,024文字。	`"${{ .steps.getResults.outputs.nextToken }}"`
`maxResults`	整数	オプション。1ページあたりに返す行の最大数です。範囲：1–1,000。	`100`
`queryResultType`	弦	オプション。返す結果のタイプです。許可される値：`DATA_ROWS`（デフォルト）、`DATA_MANIFEST`。	`"DATA_ROWS"`
`selectors`	リスト	オプション。アクションの出力から特定のフィールドを抽出するためのJQセレクター。	`[{"name": "rows", "expression": ".response.ResultSet.Rows"}, {"name": "nextToken", "expression": ".response.NextToken"}]`

次の表は、このアクションの出力フィールドについて説明しています。

出力	タイプ	例
`response`	オブジェクト	`UpdateCount`、`ResultSet`（`Rows`および`ResultSetMetadata.ColumnInfo`を含む）、およびさらにページが存在する場合は`NextToken`が含まれます。`Rows`の最初の行は常にヘッダー行です。GetQueryResults APIリファレンスをご覧ください。
`success`	ブール値	`true` または `false`
`errorMessage`	弦	`"An error occurred (InvalidRequestException) when calling the GetQueryResults operation: ..."`

例

name: get-athena-query-results
description: Fetch results of a completed Athena query
steps:
  - name: getResults
    type: action
    action: aws.athena.getQueryResults
    version: '1'
    inputs:
      awsRoleArn: ${{ :secrets:awsRoleArn }}
      region: us-east-2
      queryExecutionId: "8d0105c1-30b5-4b8f-a23e-a1b60047c43f"
      maxResults: 100
      selectors:
        - name: rows
          expression: ".response.ResultSet.Rows"
        - name: columnInfo
          expression: ".response.ResultSet.ResultSetMetadata.ColumnInfo"
        - name: nextToken
          expression: ".response.NextToken"
    next: end

この機械翻訳は、参考として提供されています。

前提条件.css-21sua1{background:none;border:none;width:0;padding:0;}

クエリの実行を開始します。

クエリ実行の取得

クエリ結果を取得

前提条件