接続の確立

CData Cmdlets ユーザーは、データモジュールをインストールし、接続プロパティを設定してスクリプトを開始できます。このセクションでは、CSV インポートおよびエクスポートcmdlet などのネイティブPowerShell cmdlet でAmazonAthena Cmdlets を使用する例を示します。

インストールおよび接続

PSGet がある場合は、PowerShell Gallery から次のコマンドを使ってcmdlet をインストールできます。CData サイトからセットアップを取得することもできます。

Install-Module AmazonAthenaCmdlets

プロファイルに以下を追加すると、次のセッションでcmdlet がロードされます。

Import-Module AmazonAthenaCmdlets;

Connect-AmazonAthena cmdlet を使って、別のcmdlet に渡すことができる接続オブジェクトを作成します。

$conn = Connect-AmazonAthena AWSAccessKey "a123" -AWSSecretKey "s123" -AWSRegion "IRELAND" -Database "sampledb" -S3StagingDirectory "s3://bucket/staging/"

Amazon Athena への接続

データへの接続には、以下を設定してください。

DataSource：接続するAmazon Athena データソース名。
Database：接続するAmazon Athena データベース名。
AWSRegion：Amazon Athena データがホストされているリージョンに設定。
S3StagingDirectory：クエリの結果を格納するS3 内のフォルダに設定。

Database またはDataSource が設定されていない場合、本製品はAmazon Athena の利用可能なデータソースからすべてのデータベースをリストしようと試みます。両方のプロパティを設定することで本製品のパフォーマンスが向上します。

Amazon Athena への認証

すべての接続に必要な基本的な接続情報の指定に加えて、以下のオプションから認証方法をいずれか1つ選択する必要があります。

AWS キーを取得

IAM ユーザーの認証情報を取得するには：

IAM コンソールにサインインします。
ナビゲーションペインでユーザーを選択します。
ユーザーのアクセスキーを作成または管理するには、ユーザーを選択してからセキュリティ認証情報タブを選択します。

AWS ルートアカウントの資格情報を取得するには：

ルートアカウントの認証情報を使用してAWS 管理コンソールにサインインします。
アカウント名または番号を選択します。
表示されたメニューでMy Security Credentials を選択します。
ルートアカウントのアクセスキーを管理または作成するには、Continue to Security Credentials をクリックし、［Access Keys］セクションを展開します。

ルートクレデンシャル

アカウントのルートクレデンシャルで認証するには、次の設定パラメータを設定します。

AuthScheme：AwsRootKeys。
AWSAccessKey：AWS ルートアカウントに紐づいているアクセスキー。
AWSSecretKey：AWS ルートアカウントに紐づいているシークレットキー。

Note： この認証スキームの使用は、簡単なテスト以外ではAmazon では推奨されていません。アカウントのルート認証情報はユーザーの完全な権限を持つため、これが最も安全性の低い認証方法になります。

多要素認証が必要な場合は、以下を指定します。

CredentialsLocation：MFA クレデンシャルが保存される設定ファイルの場所。詳しくは、接続文字列オプションのCredentials File Location のページを参照してください。
MFASerialNumber：MFA デバイスが使用されている場合は、そのシリアル番号。
MFAToken：MFA デバイスから利用できる一時トークン。

これにより、本製品は一時的な認証情報を取得するために、リクエストでMFA 認証情報を送信します。

Note： 一時的な認証情報の有効期間（デフォルトは3600秒）を制御するには、TemporaryTokenDuration プロパティを設定します。

一時クレデンシャル

一時クレデンシャルで認証するには、次を設定します。

AuthScheme：TemporaryCredentials。
AWSAccessKey：ロールを担うIAM ユーザーのアクセスキー。
AWSSecretKey：ロールを担うIAM ユーザーのシークレットキー。
AWSSessionToken：一時クレデンシャルと共に提供されるAWS のセッショントークン。詳細はAWS Identity and Access Management ユーザーガイドを参照してください。

本製品は、一時クレデンシャルの有効期間中、長期的な認証情報（IAM ユーザー認証情報など）によって提供されるものと同じ権限を使用してリソースをリクエストできるようになりました。

一時クレデンシャルおよびIAM ロールの両方を使用して認証するには、上記のすべてのパラメータを設定し、さらに以下のパラメータを指定します。

AWSRoleARN：認証したいロールのRole ARN を指定。これにより、本製品は指定されたロールの認証情報を取得しようと試みます。
AWSExternalId（オプション）：別のAWS アカウントでロールを引き受ける場合にのみ必要です。

多要素認証が必要な場合は、以下を指定します。

CredentialsLocation：MFA クレデンシャルが保存される設定ファイルの場所。詳しくは、接続文字列オプションのCredentials File Location のページを参照してください。
MFASerialNumber：MFA デバイスが使用されている場合は、そのシリアル番号。
MFAToken：MFA デバイスから利用できる一時トークン。

これにより、本製品は一時的な認証情報を取得するために、リクエストでMFA 認証情報を送信します。

Note： 一時的な認証情報の有効期間（デフォルトは3600秒）を制御するには、TemporaryTokenDuration プロパティを設定します。

EC2 Instances

AuthScheme をAwsEC2Roles に設定します。

EC2 インスタンスから本製品を使用していて、そのインスタンスにIAM ロールが割り当てられている場合は、認証にIAM ロールを使用できます。本製品は自動的にIAM ロールの認証情報を取得し、それらを使って認証するため、AWSAccessKey およびAWSSecretKey を指定する必要はありません。

認証にIAM ロールも使用している場合は、さらに以下を指定する必要があります。

AWSRoleARN：認証したいロールのRole ARN を指定。これにより、本製品は指定されたロールの認証情報を取得しようと試みます。
AWSExternalId（オプション）：別のAWS アカウントでロールを引き受ける場合にのみ必要です。

IMDSv2 サポート

Amazon Athena 本製品は、IMDSv2 をサポートしています。IMDSv1 とは異なり、新バージョンでは認証トークンが必須です。エンドポイントおよびレスポンスは、両バージョンで同じです。

IMDSv2 では、Amazon Athena 本製品はまずIMDSv2 メタデータトークンの取得を試み、それを使用してAWS メタデータエンドポイントを呼び出します。トークンを取得できない場合、本製品はIMDSv1 を使用します。

AWS Web Identity

AuthScheme をAwsWebIdentity に設定します。

Web ID でロールを割り当てられるように構成されたコンテナ（OpenID Provider を持つEKS クラスタ内のPod など）から本製品を使用する場合、またはIAM ロールに関連付けられたWeb ID プロバイダーで認証してID トークンを取得する場合は、Web ID トークンとIAM ロールの情報を一時的なセキュリティ認証情報と交換し、AWS サービスを認証してアクセスすることができます。コンテナの環境変数にAWS_ROLE_ARN とAWS_WEB_IDENTITY_TOKEN_FILE が指定されている場合、本製品は自動的に認証情報を取得します。または、AWSRoleARN とAWSWebIdentityToken の両方を指定し、AssumeRoleWithWebIdentity API 操作を実行して認証することもできます。

AWS IAM Roles

AuthScheme をAwsIAMRoles に設定します。

多くの場合、認証にはAWS ルートユーザーのダイレクトなセキュリティ認証情報ではなく、IAM ロールを使用することをお勧めします。AWS ルートユーザーのAWSAccessKey およびAWSSecretKey を指定している場合、ロールは使用できない場合があります。

AWS ロールとして認証するには、次のプロパティを設定します。

AWSAccessKey：ロールを担うIAM ユーザーのアクセスキー。
AWSSecretKey：ロールを担うIAM ユーザーのシークレットキー。
AWSRoleARN：認証したいロールのRole ARN を指定。これにより、本製品は指定されたロールの認証情報を取得しようと試みます。
AWSExternalId（オプション）：別のAWS アカウントでロールを引き受ける場合にのみ必要です。

多要素認証が必要な場合は、以下を指定します。

CredentialsLocation：MFA クレデンシャルが保存される設定ファイルの場所。詳しくは、接続文字列オプションのCredentials File Location のページを参照してください。
MFASerialNumber：MFA デバイスが使用されている場合は、そのシリアル番号。
MFAToken：MFA デバイスから利用できる一時トークン。

これにより、本製品は一時的な認証情報を取得するために、リクエストでMFA 認証情報を送信します。

Note： 一時的な認証情報の有効期間（デフォルトは3600秒）を制御するには、TemporaryTokenDuration プロパティを設定します。

ADFS

ADFS に接続するには、AuthScheme をADFS に設定し、次のプロパティを設定します。

User：ADFS ユーザー。
Password：ADFS ユーザーのパスワード。
SSOLoginURL：SSO プロバイダーのログインURL。

接続文字列の例：

AuthScheme=ADFS; AWSRegion=Ireland; Database=sampledb; [email protected]; Password=CH8WerW121235647iCa6; SSOLoginURL='https://adfs.domain.com'; AWSRoleArn=arn:aws:iam::1234:role/ADFS_SSO; AWSPrincipalArn=arn:aws:iam::1234:saml-provider/ADFSProvider; S3StagingDirectory=s3://athena/staging;

ADFS 統合

ADFS 統合フローでは、現在ログインしているWindows ユーザーの資格情報で接続します。 ADFS 統合フローを使用するには、User およびPassword を指定せず、それ以外の設定は上記のADFS ガイドと同じ手順を実行してください。

Okta

Okta に接続するには、AuthScheme をOkta に設定し、次のプロパティを設定します。

User：Okta ユーザー。
Password：Okta ユーザーのパスワード。
SSOLoginURL：SSO プロバイダーのログインURL。

Okta クライアントリクエストコンテキストをオーバーライドする信頼されたアプリケーションまたはプロキシを使用する場合、またはMFA を設定している場合は、Okta を使用して認証するためにSSOProperties を組み合わせて使用する必要があります。必要に応じて、以下のいずれかを設定します。

APIToken：Okta クライアントリクエストコンテキストをオーバーライドする、信頼されたアプリケーションまたはプロキシ経由でユーザーを認証する場合、これを顧客がOkta 組織で作成したAPI Token に設定します。
MFAType：MFA フローを設定した場合、次の対応するタイプのいずれかに設定します：OktaVerify、Email、またはSMS。
MFAPassCode：MFA フローを設定した場合は、有効なパスコードに設定します。
これを空欄または無効な値に設定した場合、本製品はユーザーのデバイスまたはE メールにワンタイムパスワードチャレンジを発行します。パスコードを受信後、取得したワンタイムパスワードをMFAPassCode 接続プロパティに設定する接続を再度開きます。
MFARememberDevice：デフォルトはTrue です。Okta は、MFA が必要な場合にデバイスを記憶させることをサポートします。設定された認証ポリシーに従ってデバイスの記憶が許可されている場合、本製品はMFA 認証の有効期間を延長するデバイストークンを送信します。MFA を記憶させない場合は、この変数をFalse に設定してください。

接続文字列の例：

AuthScheme=Okta; AWSRegion=Ireland; Database=sampledb; [email protected]; Password=CH8WerW121235647iCa6; SSOLoginURL='https://cdata-us.okta.com/home/amazon_aws/0oa35m8arsAL5f5NrE6NdA356/272'; SSOProperties='ApiToken=01230GGG2ceAnm_tPAf4MhiMELXZ0L0N1pAYrO1VR-hGQSf;'; AWSRoleArn=arn:aws:iam::1234:role/Okta_SSO; AWSPrincipalARN=arn:aws:iam::1234:saml-provider/OktaProvider; S3StagingDirectory=s3://athena/staging;

PingFederate に接続するには、AuthScheme をPingFederate に設定し、次のプロパティを設定します。

User：PingFederate ユーザー。
Password：PingFederate ユーザーのパスワード。
SSOLoginURL：SSO プロバイダーのログインURL。
AWSRoleARN（オプション）：複数のロールARN がある場合は、認可に使用するARN を指定します。
AWSPrincipalARN（オプション）：複数のプリンシパルARN がある場合は、認可に使用するARN を指定します。
SSOExchangeUrl: The Partner Service Identifier URI configured in your PingFederate server instance under: SP Connections > SP Connection > WS-Trust > Protocol Settings. This should uniquely identify a PingFederate SP Connection, so it is a good idea to set it to your AWS SSO ACS URL. You can find it under AWS SSO > Settings > View Details next to the Authentication field.
SSOProperties（オプション）：Amazon S3へのリクエストにユーザー名とパスワードを認可ヘッダーとして含める場合は、Authscheme=Basic。

SSOLoginURL 用の相互SSL 認証（WS-Trust STS エンドポイント）を有効化するには、次の SSOProperties を設定します。

SSLClientCert
SSLClientCertType
SSLClientCertSubject
SSLClientCertPassword

接続文字列の例：

authScheme=pingfederate;SSOLoginURL=https://mycustomserver.com:9033/idp/sts.wst;SSOExchangeUrl=https://us-east-1.signin.aws.amazon.com/platform/saml/acs/764ef411-xxxxxx;user=admin;password=PassValue;AWSPrincipalARN=arn:aws:iam::215338515180:saml-provider/pingFederate;AWSRoleArn=arn:aws:iam::215338515180:role/SSOTest2;AWSRegion=Ireland;S3StagingDirectory=s3://somedirectory/staging;Database=athenadatabase;

クレデンシャルファイル

認証にはクレデンシャルファイルを使用することができます。AccessKey/SecretKey 認証、一時クレデンシャル、ロール認証、またはMFA に関連するすべての設定が使用できます。これを行うには、次のプロパティを設定して認証します。

AuthScheme：AwsCredentialsFile。
AWSCredentialsFile：クレデンシャルファイルの場所。
AWSCredentialsFileProfile（オプション）：指定したクレデンシャルファイルから使用するプロファイルの名前。指定しない場合は、default という名前のプロファイルが使用されます。

詳細はAWS Command Line Interface ユーザーガイドを参照してください。

AWS Cognito クレデンシャル

AWS Cognito のユーザープールに登録されたユーザーで本製品を使用する場合は、以下のプロパティを設定して認証してください。

AuthScheme：AwsCognitoSrp に設定（推奨）。また、AwsCognitoBasic を使用することもできます。
AWSCognitoRegion：ユーザープールのリージョンに設定。
AWSUserPoolId：ユーザープールのId に設定。
AWSUserPoolClientAppId：ユーザープールのアプリクライアントId に設定。
AWSUserPoolClientAppSecret：ユーザープールのクライアントシークレットに設定。
AWSIdentityPoolId：ユーザープールとリンクしているID プールのId に設定。
User：ユーザープールに登録されているユーザーのユーザー名に設定。
Password：ユーザープールに登録されているユーザーのパスワードに設定。

Azure Active Directory / Microsoft Entra ID

NOTE： Azure AD はMicrosoft Entra ID に名称変更されました。

この構成には、2.0 On-Behalf-Of フロー（Microsoft ID プラットフォームとOAuth 2.0 On-Behalf-Of フロー）を使用し、Microsoft Entra アプリケーションが2 つ必要です。

シングルサインオンに使用される"Amazon Athena" アプリケーション
"Amazon Athena" アプリケーションに対するuser_impersonation 権限を持つ別の"コネクタ" アプリケーション。

Microsoft のAWS Single-Account Access ドキュメントに記載されている手順に従って、SSO アプリケーションを作成し、AWS シングルアカウントアプリケーションのSAML IdP としてMicrosoft Entra ID を設定します。

SSO アプリケーションにuser_impersonation 権限を持つアプリケーションを作成するには、以下の手順に従ってください。

クラウドアプリケーション管理者以上の権限でMicrosoft Entra 管理センターにサインインします。
ID -> Applications -> アプリの登録に移動します。
ページ上部の新規登録をクリックします。
名前を入力し、サポートされているアカウントの種類を適宜選択します。
リダイレクトURL ドロップダウンでWeb を選択し、http://localhost:33333 と入力します。
登録を選択します。
"Overview" セクションに、OAuthClientId（アプリケーションID）が表示されます。
API のアクセス許可 -> アクセス許可の追加を選択します。
［所属する組織で使用しているAPI］タブでAPI 名またはアプリケーションID を指定してSSO アプリケーションのAPI を選択します。
利用可能なアクセス許可のリストからuser_impersonation を選択します。
アクセス許可の追加を選択します。
証明書とシークレットを選択します。
新しいクライアントシークレットを選択します。
オプションで、説明を入力してデフォルトの有効期限を変更し、追加を選択します。
クライアントシークレット（表示されるOAuth シークレットの［値］フィールド）を控えておきます。

両方のアプリケーションを設定した後、以下のOAuth 接続プロパティを指定してドライバーと接続します。

OAuthClientId：アプリケーション登録の概要セクションにリストされている、コネクタアプリケーションのアプリケーションId。
OAuthClientSecret：コネクタアプリケーションのクライアントシークレット値。新しいクライアントシークレットを作成すると、Azure AD にこれが表示されます。
CallbackURL：コネクタアプリケーションのリダイレクトURI に設定。例：https://localhost:33333。
InitiateOAuth： GETANDREFRESH。

以下のSSOProperties を使用して、AzureAD へ認証します。

Resource：アプリケーション登録の概要セクションにリストされている、Amazon Athena アプリケーションのアプリケーションId URI。ほとんどの場合、これはカスタムAmazon Athena ドメインのURL です。
AzureTenant：アプリケーションが登録されているAzure AD テナントのId。

次は接続文字列の例です。

AuthScheme=AzureAD;InitiateOAuth=GETANDREFRESH;OAuthClientId=3ea1c786-d527-4399-8c3b-2e3696ae4b48;OauthClientSecret=xxx;CallbackUrl=https://localhost:33333;SSOProperties='Resource=https://signin.aws.amazon.com/saml;AzureTenant=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

データの取得

Select-AmazonAthena cmdlet はデータを取得するためのネイティブなPowerShell インターフェースを提供します。

$results = Select-AmazonAthena -Connection $conn -Table "[AwsDataCatalog].[sampledb].Customers" -Columns @("Name, TotalDue") -Where "CustomerId='12345'"

Invoke-AmazonAthena cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。

cmdlet 出力のパイプ処理

cmdlet は行オブジェクトをパイプラインに一度に一行ずつ返します。以下は、結果をCSV ファイルにエクスポートします。

Select-AmazonAthena -Connection $conn -Table [AwsDataCatalog].[sampledb].Customers -Where "CustomerId = '12345'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\my[AwsDataCatalog].[sampledb].CustomersData.csv -NoTypeInformation

Select-AmazonAthena からの結果をSelect-Object cmdlet にパイプして、Export-CSV cmdlet にパイプする前にいくつかのプロパティを実行していることがわかるでしょう。これをする理由は、CData Cmdlets は接続、テーブル、およびカラムの情報を結果セットの各行オブジェクトに追加しますが、必ずしもその情報がCSV ファイルに必要ではないからです。

ただし、これによってcmdlet の出力を別のcmdlet にパイプすることが容易になります。以下に、結果セットをJSON に変換する例を示します。

 
PS C:\> $conn  = Connect-AmazonAthena AWSAccessKey "a123" -AWSSecretKey "s123" -AWSRegion "IRELAND" -Database "sampledb" -S3StagingDirectory "s3://bucket/staging/"
PS C:\> $row = Select-AmazonAthena -Connection $conn -Table "[AwsDataCatalog].[sampledb].Customers" -Columns (Name, TotalDue) -Where "CustomerId = '12345'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "[AwsDataCatalog].[sampledb].Customers",
  "Columns":  [

  ],
  "Name":  "MyName",
  "TotalDue":  "MyTotalDue"
}

Cmdlets for Amazon Athena

接続の確立

インストールおよび接続

Amazon Athena への接続

Amazon Athena への認証

AWS キーを取得

ルートクレデンシャル

一時クレデンシャル

EC2 Instances

IMDSv2 サポート

AWS Web Identity

AWS IAM Roles

ADFS

ADFS 統合

Okta

クレデンシャルファイル

AWS Cognito クレデンシャル

Azure Active Directory / Microsoft Entra ID

データの取得

cmdlet 出力のパイプ処理