接続の確立

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

インストールおよび接続

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

Install-Module ApacheCouchDBCmdlets

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

Import-Module ApacheCouchDBCmdlets;

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

$conn = Connect-ApacheCouchDB -User 'abc123' -Password 'abcdef'

Apache CouchDB への接続

Apache CouchDB は3種類の認証をサポートします。

Basic：基本的なユーザー名 / パスワード認証。
JWT：JWT トークンによる認証。
None：パブリックなデータベースへの匿名アクセス。

ユーザー（またはJWT トークン）が特定のデータベースだけにアクセスできるようにしたい場合は、Apache CouchDB インスタンスでadmin_only_all_dbs オプションを設定し、テーブルをリストするために本製品が必要とする"/_all_dbs" エンドポイントへのアクセス権をすべてのユーザーに付与する必要があります。そうしない場合、エンドポイントは認証エラーをスローするため本製品は接続することができません。

Basic 認証

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

AuthScheme：Basic。
Url：Apache CouchDB インスタンスのURL。例：http://localhost:5984
User：認証に使用されるApache CouchDB ユーザーアカウント。
Password：認証するユーザーに関連付けられたApache CouchDB パスワード。

JWT Authentication

The following connection properties are required and must always be specified:

AuthScheme: JWT.
Url: The Url of your Apache CouchDB instance. For example: http://localhost:5984.

From here you can:

1. Set the following so that the 本製品 automatically generates (and refreshes if applicable) the tokens for you:

Required

JWTSubject: The name of the user to assign to the JWT token.
JWTAlgorithm: The algorithm to use for the JWT token signature.
JWTKeyType: The type of the encryption key.
JWTKey: The encryption key used to sign the JWT token generated by the 本製品.

Optional

JWTIssuer: The issuer of the JWT token.
JWTExpiration: How long the JWT token should remain valid, in seconds.
JWTHeaders: A collection of extra headers that should be included in the JWT header.
JWTClaims: A collection of extra claims that should be included in the JWT payload.
CredentialsLocation: The location of the settings file where the JWT token is saved.

2. Or you can generate the tokens yourself manually and pass them to the 本製品 by using the JWTToken connection property.

Generating the key pair

When using asymmetric algorithms to sign the tokens, you must generate a private/public key pair. For that, a cryptographic library like OpenSSL can be used. For example:

# generate private key
openssl genrsa --out private_rsa256.pem 2048

# extract public key
openssl rsa -in private_rsa256.pem -pubout > public_rsa256.pem

JWT Configurations

Refer to CouchDB JWT Authentication Documentation for the following.

The alg and sub are required claims and will always be validated by the Apache CouchDB instance. Other required claims can be configured in the server (see required_claims). In that case, you must use JWTHeaders and JWTClaims so that the 本製品 can include those additional claims when generating the JWT token.

You can use roles_claim_name or the roles_claim_path options to assign roles to the JWT tokens.

Refer to the following example for configuring the server and the 本製品:

server configuration

[chttpd]
...
authentication_handlers = {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, default_authentication_handler}
admin_only_all_dbs = false
...

[jwt_auth]
...
required_claims = exp
roles_claim_path = my.nested._couchdb\.roles
rsa:rsa_256 = -----BEGIN PUBLIC KEY-----\nYOUR_PUBLIC_KEY\n-----END PUBLIC KEY-----\n
...

本製品 configuration

Url=http://localhost:5984;
JWTSubject=JWT User 1;
JWTAlgorithm=RS256;
JWTKeyType=PEMKEY_FILE;
JWTKey=PATH_TO_FOLDER\private_rsa256.pem;
JWTHeaders=kid : rsa_256 | Custom Header 1 : Test 1;
JWTClaims= my : eyJuZXN0ZWQiOnsiX2NvdWNoZGIucm9sZXMiOlsidXNlcjIiXX19 | Custom Claim 1 : Test 1;

Anonymous

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

AuthScheme：None。
Url：Apache CouchDB インスタンスのURL。例：http://localhost:5984
PublicDatabases：テーブルとしてリストする公開データベースのカンマ区切りリスト。

データの取得

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

$results = Select-ApacheCouchDB -Connection $conn -Table "Movies" -Columns @("MovieRuntime, MovieRating") -Where "MovieRating='R'"

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

cmdlet 出力のパイプ処理

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

Select-ApacheCouchDB -Connection $conn -Table Movies -Where "MovieRating = 'R'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myMoviesData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-ApacheCouchDB -User 'abc123' -Password 'abcdef'
PS C:\> $row = Select-ApacheCouchDB -Connection $conn -Table "Movies" -Columns (MovieRuntime, MovieRating) -Where "MovieRating = 'R'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Movies",
  "Columns":  [

  ],
  "MovieRuntime":  "MyMovieRuntime",
  "MovieRating":  "MyMovieRating"
}

データの削除

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

Select-ApacheCouchDB -Connection $conn -Table Movies -Where "MovieRating = 'R'" | Remove-ApacheCouchDB

データの変更

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

Import-Csv -Path C:\MyMoviesUpdates.csv | %{
  $record = Select-ApacheCouchDB -Connection $conn -Table Movies -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-ApacheCouchDB -Connection $conn -Table Movies -Columns @("MovieRuntime","MovieRating") -Values @($_.MovieRuntime, $_.MovieRating) -Where "Id  = `'$_.Id`'"
  }else{
    Add-ApacheCouchDB -Connection $conn -Table Movies -Columns @("MovieRuntime","MovieRating") -Values @($_.MovieRuntime, $_.MovieRating)
  }
}

Cmdlets for Apache CouchDB