Cmdlets for PingOne

Build 25.0.9434

接続の確立

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

PingOne への接続

PingOne に接続するには以下のプロパティを設定します。

  • Region：自身のPingOne 組織のデータがホスティングされている地域。
  • AuthScheme：PingOne に接続する際に使用する認証の種類。
  • WorkerAppEnvironmentId（デフォルトのPingOne ドメインを使用する場合に必要）、またはAuthorizationServerURL のいずれかで、下に説明するように設定します。

WorkerAppEnvironmentId の設定

WorkerAppEnvironmentId は、Worker アプリケーションが存在するPingOne 環境のID です。 このパラメータは、環境がデフォルトのPingOne ドメイン（auth.pingone）を利用している場合のみ使用されます。 これは、カスタムOAuth アプリケーションの作成 で説明するように、PingOne への認証に使用するカスタムOAuth アプリケーションを作成した後に設定します。

はじめに、このプロパティの値を見つけます。

  1. 自身のPingOne 組織のホームページからナビゲーションサイドバーに移動し、Environments をクリックします。
  2. OAuth / Worker のカスタムアプリケーションを作成した環境（通常はAdministrators）を見つけ、Manage Environment をクリックします。 環境のホームページが表示されます。
  3. 環境のホームページのナビゲーションサイドバーで、Applications をクリックします。
  4. リストから、OAuth またはWorker アプリケーションの詳細を見つけます。
  5. Environment ID フィールドの値をコピーします。 以下の例に似たものになるはずです：
    WorkerAppEnvironmentId='11e96fc7-aa4d-4a60-8196-9acf91424eca';

次に、WorkerAppEnvironmentId をEnvironment ID フィールドの値に設定します。

AuthorizationServerURL の設定

AuthorizationServerURL は、お使いのアプリケーションが配置されている環境のPingOne 認可サーバーのベースURL です。 このプロパティは、PingOne プラットフォームAPI ドキュメントで説明されているように、環境にカスタムドメインを設定した場合にのみ使用されます。 Custom Domains を参照してください。

PingOne への認証

PingOne はOAuth とOAuthClient 認証の両方をサポートしています。 上述の設定手順に加え、OAuth またはOAuthCliet 認証をサポートするために、さらに2つの手順を完了する必要があります。

  • カスタムOAuth アプリケーションの作成 で説明するように、カスタムOAuth アプリケーションを作成して設定します。
  • 本製品 がデータモデル 内のエンティティにアクセスできるようにするには、Administrator Roles での説明のとおり、使用するアドミンユーザー / ワーカーアプリケーションに対して正しいロールを設定していることを確認してください。
  • 以下のサブセクションで説明されているように、選択した認証スキームと認証フローに適切なプロパティを設定します。

OAuth（認可コードグラント）

AuthScheme をOAuth に設定します。

デスクトップアプリケーション

OAuth アクセストークンの取得およびリフレッシュ

以下を設定して、接続してください。

  • OAuthClientId：カスタムOAuth アプリケーションを作成した際に取得したClient ID。
  • OAuthClientSecret：カスタムOAuth アプリケーションを作成した際に取得したClient Secret。
  • CallbackURL：カスタムOAuth アプリケーションの登録時に定義したリダイレクトURI。例：https://localhost:3333

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

ヘッドレスマシン

ドライバーを設定するため、ヘッドレスマシンでユーザーアカウントにOAuth を使用します。インターネットブラウザに対応した別の端末で認証する必要があります。

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

  • オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
  • オプション2：インターネットブラウザに対応したマシンに本製品 をインストールし、通常のブラウザベースのフローで認証した後でOAuth 認証値を転送します。

次に、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。

オプション1：Verifier code を取得および交換

Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。

インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得する方法は次のとおりです。

  1. 次のプロパティを設定します。
    • InitiateOAuth：OFF に設定。
    • OAuthClientId：カスタムOAuth アプリケーションを設定した際に取得したClient ID。
    • OAuthClientSecret：カスタムOAuth アプリケーションを設定した際に取得したClient Secret。
    次に、適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
  2. ログインして、本製品 にアクセス許可を与えます。すると、リダイレクトURI にリダイレクトされます。リダイレクトURI にはcode というパラメータが付加されます。このパラメータの値を控えておきます。後ほどこれをOAuthVerifier 接続プロパティに設定します。
次に、OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換する必要があります。

ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。

  • InitiateOAuth：REFRESH。
  • OAuthVerifier：控えておいたverifier code（リダイレクトURI のcode パラメータの値）。
  • OAuthClientId：カスタムOAuth アプリケーションを設定した際に取得したClient ID。
  • OAuthClientSecret：カスタムOAuth アプリケーションを設定した際に取得したClient Secret。
  • OAuthSettingsLocation：暗号化されたOAuth 認証値を保存する場所を指定します。

接続をテストしてOAuth 設定ファイルを生成し、以下のプロパティを再設定して接続します。

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

オプション2：OAuth 設定を転送

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

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

接続をテストしてOAuth 設定ファイルを生成し、OAuth 設定ファイルをヘッドレスマシンにコピーします。

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

  • InitiateOAuth：REFRESH。
  • OAuthClientId：カスタムOAuth アプリケーションを設定した際に取得したClient ID。
  • OAuthClientSecret：カスタムOAuth アプリケーションを設定した際に取得したClient Secret。
  • OAuthSettingsLocation：ブラウザでマシンからコピーしたOAuth 設定ファイルの場所。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。

OAuthClient（クライアントクレデンシャルグラント）

AuthScheme をOAuthClient に設定します。

OAuth の自動リフレッシュ

OAuth アクセストークンの取得およびリフレッシュ

以下を設定して、接続してください。

  • OAuthClientId：カスタムOAuth アプリケーション設定のOAuth クライアントID。
  • OAuthClientSecret：カスタムOAuth アプリケーション設定のOAuth クライアントシークレット。

接続すると、本製品 は自動でOAuth プロセスを完了します。

  1. 本製品 はPingOne からアクセストークンを取得し、それを使ってデータをリクエストします。
  2. 本製品 はアクセストークンの期限が切れると自動的にリフレッシュします。
  3. OAuth 値はOAuthSettingsLocation で指定された場所に基づいてメモリに保存されます。

接続オブジェクトの作成

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

$conn = Connect-PingOne -AuthScheme 'OAuth' -WorkerAppEnvironmentId 'eebc33a8-xxxx-4f3a-yyyy-d3e5262fd49e' -Region 'NA' -OAuthClientId 'client_id' -OAuthClientSecret 'client_secret'

データの取得

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

$results = Select-PingOne -Connection $conn -Table "[CData].[Administrators].Users" -Columns @("Username, Email") -Where "Id='39ef9b6f-5973-4701-bd19-7950d4b7d6e0'"
Invoke-PingOne cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。

cmdlet 出力のパイプ処理

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

Select-PingOne -Connection $conn -Table [CData].[Administrators].Users -Where "Id = '39ef9b6f-5973-4701-bd19-7950d4b7d6e0'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\my[CData].[Administrators].UsersData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-PingOne -AuthScheme 'OAuth' -WorkerAppEnvironmentId 'eebc33a8-xxxx-4f3a-yyyy-d3e5262fd49e' -Region 'NA' -OAuthClientId 'client_id' -OAuthClientSecret 'client_secret'
PS C:\> $row = Select-PingOne -Connection $conn -Table "[CData].[Administrators].Users" -Columns (Username, Email) -Where "Id = '39ef9b6f-5973-4701-bd19-7950d4b7d6e0'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "[CData].[Administrators].Users",
  "Columns":  [

  ],
  "Username":  "MyUsername",
  "Email":  "MyEmail"
}

データの削除

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

Select-PingOne -Connection $conn -Table [CData].[Administrators].Users -Where "Id = '39ef9b6f-5973-4701-bd19-7950d4b7d6e0'" | Remove-PingOne

データの変更

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

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

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