Cmdlets for MariaDB

Build 25.0.9434

接続の確立

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

MariaDB への接続

次のプロパティを設定し、MariaDB データに接続します。

  • Server：MariaDB データベースをホスティングしているサーバーのホスト名またはIP アドレス。
  • Port：MariaDB データベースをホスティングしているサーバーのポート。
  • Database（オプション）：接続先のデフォルトデータベース。設定されていない場合、MariaDB は使用可能なすべてのデータベースからテーブルを返します。

MariaDB への認証

MariaDB は次の認証をサポートします。

  • 標準
  • NT Lan Manager（NTLM）
  • LDAP
  • SSL
  • SSH
  • Azure

標準認証

標準認証で認証するには、AuthScheme をPassword に設定し、以下のプロパティを設定します。

  • User：認証するMariaDB ユーザーのユーザー名。
  • Password：認証するMariaDB ユーザーに関連付けられたパスワード。

NTLM

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

デフォルトでは、本製品 は、実行中のPC のドメインまたはMariaDB インスタンスを実行しているマシンで使用されているドメインのいずれかを使用して、ユーザー資格情報とNTLM ドメインを自動的に決定します。

異なるドメインを指定したい場合は、異なるログイン認証情報を提供するか、あるいは以下のオプション接続プロパティのいずれかまたはすべてを使用してターゲットNTLM バージョンを変更します。

  • User：認証するNTLM ユーザー。
  • Password：認証するNTLM ユーザーのパスワード。
  • Domain：接続するドメイン名。
  • NTLMVersion：本製品 で使用されるNTLM のバージョン。

LDAP

LDAP ユーザーとして認証するには、AuthScheme をLDAP に設定します。

デフォルトでは、本製品 はLDAP 認証情報を自動検出します。 特定のユーザーとパスワードを指定したい場合は、以下のオプション接続プロパティを設定します。

  • User：ログインするユーザー。
  • Password：ユーザーのパスワード。

SSL

SSL 認証を使用してMariaDB データに安全に接続するには、以下の接続プロパティを設定します。

  • SSLClientCert：クライアント証明書のための証明書ストア名。相互（双方向）SSL で使用されます。
  • SSLClientCertPassword：パスワードで保護されている場合、クライアント証明書ストアのパスワード。
  • SSLClientCertSubject：TLS / SSL クライアント証明書のサブジェクト。ストア内の証明書を検索するために使用されます。
  • SSLClientCertType：クライアント証明書ストアの種類。
  • SSLServerCert：MariaDB サーバーが受け入れ可能な証明書。

SSH

SSH 経由でリモートマシンを認証し、MariaDB データにアクセスするには、以下の接続プロパティを設定します。

  • SSHClientCert：クライアント証明書のための証明書ストア名。
  • SSHClientCertPassword：クライアント証明書ストアがパスワードで保護されている場合、この値をストアのパスワードに設定。
  • SSHClientCertSubject：TLS / SSL クライアント証明書のサブジェクト。ストア内の証明書を検索するために使用されます。
  • SSHClientCertType：クライアントストアの証明書タイプ。
  • SSHPassword：SSH サーバーに認証するためのパスワード。
  • SSHPort：SSH 操作に使用されるポート。
  • SSHServer：認証を試行中のSSH 認証サーバー。
  • RSBHelpinfo_p_SSHServerFingerprint：接続を試行中のホストの検証に使用される、SSH サーバーの指紋。
  • SSHUser：SSH サーバーへの認証に使用するユーザー名。

Azure 認証

Azure でホストされているMariaDB データベースに接続するには、AuthScheme を以下の値のいずれかに設定します。

  • AzureAD：Microsoft Entra ID ユーザーとして認証します（OAuth ベース）。
  • AzureMSI：Azure VM またはアプリに割り当てられたマネージドサービスID を使用します。
  • AzurePassword：Azure のユーザー名およびパスワードを使用して認証します。

すべてのAzure メソッドにおいて、AzureTenant プロパティは通常、Microsoft Entra ID テナントを表し、多くの場合、companyname.microsoft.com の形式、またはAzure ポータルのEntra ID -> プロパティに表示されているディレクトリID を表します。

マネージドサービスID（AzureMSI）

マネージドID を使用して認証するには、AuthScheme をAzureMSI に設定し、以下のプロパティを構成します。

  • AzureTenant：MariaDB インスタンスがホストされているMicrosoft Online テナント。
  • OAuthClientId（オプション）：マネージドID のクライアントID。VM に複数のユーザー割り当てID がある場合は必須です。

Azure パスワード

Azure のユーザー名とパスワードを使用して認証するには、AuthScheme をAzurePassword に設定し、以下の接続プロパティを設定します。

  • User：Azure のユーザー名。
  • Password：Azure アカウントのパスワード。

Entra ID（旧称 Azure AD）

Note：Microsoft はAzure AD をEntra ID にリブランドしました。ユーザーがEntra ID 管理サイトを操作する必要があるトピックでは、Microsoft が使用している名称と同じものを使用します。ただし、名前または値が"Azure AD" を参照しているCData 接続プロパティは、依然として存在します。

Entra ID は、Microsoft のマルチテナント、クラウドベースのディレクトリおよびID 管理プラットフォームです。 OAuth ベースの認証フローに対応しており、ドライバーによるMariaDB エンドポイントへのセキュアなアクセスを実現します。

認証の手順は環境によって異なります。デスクトップアプリケーション、Web ベースのワークフロー、ヘッドレスシステムから接続する方法の詳細については、以下のセクションを参照してください。

デスクトップアプリケーション
CData は、デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。 また、MariaDB コンソールで設定および登録するカスタムOAuth アプリケーションを使用して認証することもできます。設定方法については、カスタムOAuth アプリケーションの作成 を参照してください。

接続の前に、次の接続プロパティを設定します。

  • InitiateOAuth：GETANDREFRESH。OAuthAccessToken を自動的に取得およびリフレッシュするために使用します。
  • カスタムアプリケーションのみ：
    • OAuthClientId：カスタムOAuth アプリケーションの登録時に割り当てられたクライアントId。
    • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に割り当てられたクライアントシークレット。
    • CallbackURL：カスタムOAuth アプリケーションの登録時に定義されたリダイレクトURI。

接続すると、本製品 はデフォルトブラウザでMariaDB のOAuth エンドポイントを開きます。ログインし、アプリケーションにアクセス許可を与えます。

アクセストークンの期限が切れたときは、本製品 は自動でアクセストークンをリフレッシュします。

ヘッドレスマシン
ヘッドレスマシンに置かれているリソースにログインする必要がある場合は、 インターネットブラウザに対応した別の端末で認証する必要があります。以下のいずれかの方法で行います。

  • 後述のVerifier code を取得および交換に従い、OAuthVerifier 値を取得します。
  • 別のマシンに本製品 をインストールし、通常のブラウザベースのフローで認証した後でOAuth 認証値を転送します。

いずれかのオプションを実行後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするようにドライバーを設定します。

Verifier コードを取得および交換

Verifier code を取得するには、インターネットブラウザがあるマシンからOAuth 認可URL で認証し、OAuthVerifier 接続プロパティを取得する必要があります。

  1. 以下のオプションから選択します。

    • 埋め込みOAuth アプリケーションを使用する場合は、MariaDB OAuth endpoint をクリックし、ブラウザでエンドポイントを開きます。
    • カスタムOAuth アプリケーションを使用する場合は、以下のプロパティを設定して認可URL を作成します。
      • InitiateOAuth：OFF。
      • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
      • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。
      認可URL が確立されたら、適切なCallbackURL を指定してgetoauthauthorizationurl ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。

  2. ログインして、本製品 にアクセス許可を与えます。verifier code を含むコールバックURL にリダイレクトされます。
  3. verifier code の値を保存します。後ほどこれをOAuthVerifier 接続プロパティに設定します。
次に、OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換します。

OAuth 認証値を取得するには次のプロパティを設定します。

  • InitiateOAuth：REFRESH。
  • OAuthVerifier：verifier コード。
  • OAuthSettingsLocation：ドライバーがOAuth トークン値を保存するファイルの場所。これは接続間で維持されます。
  • カスタムアプリケーションのみ：
    • OAuthClientId：（カスタムアプリのみ）カスタムOAuth アプリケーション設定のクライアントId に設定。
    • OAuthClientSecret：（カスタムアプリのみ）カスタムOAuth アプリケーション設定のクライアントシークレットに設定。

OAuth 設定ファイルが生成されたら、以下のように接続プロパティをリセットします。

  • InitiateOAuth：REFRESH。
  • OAuthSettingsLocation：暗号化されたOAuth 認証値が保存される場所。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。
  • カスタムアプリケーションのみ：
    • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
    • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。

OAuth 設定を転送

ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバーとの接続を作成し、インストールする必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。

「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定された場所に暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。

接続が正常にテストされたら、OAuth 設定ファイルをヘッドレスマシンにコピーします。

ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。

  • InitiateOAuth：REFRESH。
  • OAuthSettingsLocation：OAuth 設定ファイルの場所。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。
  • カスタムアプリケーションのみ：
    • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
    • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。

接続オブジェクトの作成

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

$conn = Connect-MariaDB -User 'myUser' -Password 'myPassword' -Database 'NorthWind' -Server 'myServer' -Port 3306

データの取得

接続の作成が完了したら、リレーショナルデータベースに対して通常行える操作を 別のcmdlet を使って実行できます。 Select-MariaDB cmdlet はデータを取得するためのネイティブなPowerShell インターフェースを提供します。 

$results = Select-MariaDB -Connection $conn -Table "Orders" -Columns @("ShipName, ShipCity") -Where "ShipCountry='USA'"
Invoke-MariaDB cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。

cmdlet 出力のパイプ処理

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

Select-MariaDB -Connection $conn -Table Orders -Where "ShipCountry = 'USA'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myOrdersData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-MariaDB -User 'myUser' -Password 'myPassword' -Database 'NorthWind' -Server 'myServer' -Port 3306
PS C:\> $row = Select-MariaDB -Connection $conn -Table "Orders" -Columns (ShipName, ShipCity) -Where "ShipCountry = 'USA'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Orders",
  "Columns":  [

  ],
  "ShipName":  "MyShipName",
  "ShipCity":  "MyShipCity"
}

データの削除

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

Select-MariaDB -Connection $conn -Table Orders -Where "ShipCountry = 'USA'" | Remove-MariaDB

データの変更

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

Import-Csv -Path C:\MyOrdersUpdates.csv | %{
  $record = Select-MariaDB -Connection $conn -Table Orders -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-MariaDB -Connection $conn -Table Orders -Columns @("ShipName","ShipCity") -Values @($_.ShipName, $_.ShipCity) -Where "Id  = `'$_.Id`'"
  }else{
    Add-MariaDB -Connection $conn -Table Orders -Columns @("ShipName","ShipCity") -Values @($_.ShipName, $_.ShipCity)
  }
}

Copyright (c) 2025 CData Software, Inc. - All rights reserved.
Build 25.0.9434