接続の確立

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

Elasticsearch サービスへの接続

データに接続するには以下を設定します。

Server は、Elasticsearch インスタンスのIP アドレスもしくはドメインに設定する必要があります。また、Server にはシングルクラスタのノードアドレス、またはホスト名のカンマ区切りのリストを設定することもできます。
```
Server=01.02.03.04 
  OR 
Server=01.01.01.01:1234,02.02.02.02:5678
```
Port は、Elasticsearch インスタンス用に構成されたポートに設定する必要があります。Server プロパティのノードの仕様にポートを含めると、そのノードに限り、その含めたポートがPort の仕様より優先されます。

本製品は、認証とTLS/SSL 暗号化にX-Pack Security を使用しています。サーバーの値の前に"https://" を付けると、TLS/SSL で接続できます。

Amazon OpenSearch Service への接続

データに接続するには以下を設定します。

Server はAmazon ES インスタンスのエンドポイントURL に設定する必要があります。
Port は443に設定します。
AWSRegion はElasticsearch インスタンスがホストされているAmazon AWS リージョンに設定する必要があります（本製品はServer 値に基づいて自動的にリージョンを識別しようとします）。

本製品は、認証とTLS/SSL 暗号化にX-Pack Security を使用しています。

Note： リクエストはAWS 署名バージョン 4 を使用して署名されています。

Elasticsearch への認証

通常の接続プロパティに加えて、次の認証方法から1つ選択してください。

AWS キーを取得

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

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

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

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

標準認証

AuthScheme をBasic に設定し、User とPassword プロパティを設定して、オプションでPKI（公開鍵暗号基盤）を使用して認証します。本製品が接続されると、X-Pack では、設定したレルムをベースにユーザー認証およびロールの許可が実施されます。

PKI を使用するには、SSLClientCert、SSLClientCertType、SSLClientCertSubject、およびSSLClientCertPassword プロパティを設定します。

Note： PKI を使用するためには、TLS/SSL およびクライアント認証はX-Pack 上で有効化されていなければなりません。

セキュアなElasticsearch への接続

本製品においてTLS/SSL を有効化するには、UseSSL をtrue に設定します。

ルートクレデンシャル

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

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 インスタンスからのAWS の使用

AuthScheme をAwsEC2Roles に設定します。

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

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

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

IMDSv2 サポート

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

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

この認証方法はOpensearch Service でのみ可能であり、Elasticsearch では利用できないことに注意してください。

AWS IAM Roles

AWS 経由で認証するには、AuthScheme をAwsIAMRoles に設定します。

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

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

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

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

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

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

Note：状況によっては、AWS ルートユーザーのダイレクトなセキュリティ認証情報よりも、IAM ロールを使用して認証する方が望ましい場合があります。AWS ルートユーザーのAWSAccessKey およびAWSSecretKey を指定している場合、ロールは使用できません。

Kerberos

Kerberos で認証する方法についての詳細は、Kerberos の使用を参照してください。

API キー

APIKey を使用して認証するには、次を設定します。

AuthScheme：APIKey に設定。
APIKey：Elasticsearch から返されたAPIKey に設定。
APIKeyId：APIKey と一緒に返されたId に設定。

接続オブジェクトの作成

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

$conn = Connect-Elasticsearch -Server '127.0.0.1' -Port 9200

データの取得

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

$results = Select-Elasticsearch -Connection $conn -Table "[CData].[Elasticsearch].Employee" -Columns @("Id, Name") -Where "Industry='Floppy Disks'"

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

cmdlet 出力のパイプ処理

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

Select-Elasticsearch -Connection $conn -Table [CData].[Elasticsearch].Employee -Where "Industry = 'Floppy Disks'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\my[CData].[Elasticsearch].EmployeeData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-Elasticsearch -Server '127.0.0.1' -Port 9200
PS C:\> $row = Select-Elasticsearch -Connection $conn -Table "[CData].[Elasticsearch].Employee" -Columns (Id, Name) -Where "Industry = 'Floppy Disks'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "[CData].[Elasticsearch].Employee",
  "Columns":  [

  ],
  "Id":  "MyId",
  "Name":  "MyName"
}

データの削除

以下は、抽出条件に合うあらゆるレコードを削除します。

Select-Elasticsearch -Connection $conn -Table [CData].[Elasticsearch].Employee -Where "Industry = 'Floppy Disks'" | Remove-Elasticsearch

データの変更

cmdlet はデータクレンジング同様、データの変換を容易にします。次の例は、レコードがすでに存在するかどうか、挿入する前に更新が必要かどうかをチェックしてから、CSV ファイルのデータをElasticsearch にロードします。

Import-Csv -Path C:\My[CData].[Elasticsearch].EmployeeUpdates.csv | %{
  $record = Select-Elasticsearch -Connection $conn -Table [CData].[Elasticsearch].Employee -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-Elasticsearch -Connection $conn -Table [CData].[Elasticsearch].Employee -Columns @("Id","Name") -Values @($_.Id, $_.Name) -Where "Id  = `'$_.Id`'"
  }else{
    Add-Elasticsearch -Connection $conn -Table [CData].[Elasticsearch].Employee -Columns @("Id","Name") -Values @($_.Id, $_.Name)
  }
}

Cmdlets for Elasticsearch

接続の確立

Elasticsearch サービスへの接続

Amazon OpenSearch Service への接続

Elasticsearch への認証

AWS キーを取得

標準認証

セキュアなElasticsearch への接続

ルートクレデンシャル

一時クレデンシャル

EC2 インスタンスからのAWS の使用

IMDSv2 サポート

AWS IAM Roles

Kerberos

API キー

接続オブジェクトの作成

データの取得

cmdlet 出力のパイプ処理

データの削除

データの変更