接続の確立
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 管理コンソールにサインインします。
- アカウント名または番号を選択します。
- 表示されたメニューでMy Security Credentials を選択します。
- ルートアカウントのアクセスキーを管理または作成するには、Continue to Security Credentials をクリックし、[Access Keys]セクションを展開します。
ルートクレデンシャル
アカウントのルートクレデンシャルで認証するには、次の設定パラメータを設定します。
- AuthScheme:AwsRootKeys。
- AWSAccessKey:AWS ルートアカウントに紐づいているアクセスキー。
- AWSSecretKey:AWS ルートアカウントに紐づいているシークレットキー。
Note: この認証スキームの使用は、簡単なテスト以外ではAmazon では推奨されていません。アカウントのルート認証情報はユーザーの完全な権限を持つため、これが最も安全性の低い認証方法になります。
一時クレデンシャル
一時クレデンシャルで認証するには、次を設定します。
- AuthScheme:TemporaryCredentials。
- AWSAccessKey:ロールを担うIAM ユーザーのアクセスキー。
- AWSSecretKey:ロールを担うIAM ユーザーのシークレットキー。
- AWSSessionToken:一時クレデンシャルと共に提供されるAWS のセッショントークン。 詳細はAWS Identity and Access Management ユーザーガイド を参照してください。
本製品 は、一時クレデンシャルの有効期間中、長期的な認証情報(IAM ユーザー認証情報など)によって提供されるものと同じ権限を使用してリソースをリクエストできるようになりました。
一時クレデンシャルおよびIAM ロールの両方を使用して認証するには、上記のすべてのパラメータを設定し、さらに以下のパラメータを指定します。
- AWSRoleARN:認証したいロールのRole ARN を指定。これにより、本製品 は指定されたロールの認証情報を取得しようと試みます。
- AWSExternalId(オプション):別のAWS アカウントでロールを引き受ける場合にのみ必要です。
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 IAM Roles
AuthScheme をAwsIAMRoles に設定します。
多くの場合、認証にはAWS ルートユーザーのダイレクトなセキュリティ認証情報ではなく、IAM ロールを使用することをお勧めします。AWS ルートユーザーのAWSAccessKey およびAWSSecretKey を指定している場合、ロールは使用できない場合があります。
AWS ロールとして認証するには、次のプロパティを設定します。
- AWSAccessKey:ロールを担うIAM ユーザーのアクセスキー。
- AWSSecretKey:ロールを担うIAM ユーザーのシークレットキー。
- AWSRoleARN:認証したいロールのRole ARN を指定。これにより、本製品 は指定されたロールの認証情報を 取得しようと試みます。
- AWSExternalId(オプション):別のAWS アカウントでロールを引き受ける場合にのみ必要です。
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;
多要素認証(MFA)
多要素認証を必要とするユーザーおよびロールには、以下を指定してください。
- AuthScheme:AwsMFA。
- CredentialsLocation:MFA クレデンシャルが保存される設定ファイルの場所。詳しくは、接続文字列オプションのCredentials File Location のページを参照してください。
- MFASerialNumber:MFA デバイスが使用されている場合は、そのシリアル番号。
- MFAToken:MFA デバイスから利用できる一時トークン。
- AWSAccessKey:MFA が発行されるIAM ユーザーのアクセスキー。
- AWSSecretKey:MFA が発行されるIAM ユーザーのシークレットキー。
- AWSRoleARN:認証したいロールのRole ARN を指定。これにより、本製品 はMFA を使用して指定されたロールの認証情報を 取得しようと試みます。
- AWSExternalId(オプション):別のAWS アカウントでロールを引き受ける場合にのみ必要です。
Note: 一時的な認証情報の有効期間(デフォルトは3600秒)を制御するには、TemporaryTokenDuration プロパティを設定します。
クレデンシャルファイル
認証にはクレデンシャルファイルを使用することができます。AccessKey/SecretKey 認証、一時クレデンシャル、ロール認証、またはMFA に関連するすべての設定が使用できます。 これを行うには、次のプロパティを設定して認証します。
- AuthScheme:AwsCredentialsFile。
- AWSCredentialsFile:クレデンシャルファイルの場所。
- AWSCredentialsFileProfile(オプション):指定したクレデンシャルファイルから使用するプロファイルの名前。指定しない場合は、default という名前のプロファイルが使用されます。
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 シークレットの[値]フィールド)を控えておきます。
- 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" }