接続の確立

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

インストールおよび接続

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

Install-Module HighriseCmdlets

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

Import-Module HighriseCmdlets;

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

$conn = Connect-Highrise -OAuthClientId 'MyOAuthClientId' -OAuthClientSecret 'MyOAuthClientSecret' -CallbackURL 'http://localhost' -AccountId 'MyAccountId'

Highrise への認証

Highrise はOAuth およびAPI トークン認証スキームをサポートします。

OAuth

Highrise はOAuth 認証標準を利用しています。Highrise へ認証するには、OAuthClientId、OAuthClientSecret、およびCallbackURL を取得する必要があります。

すべてのOAuth フローで、AuthScheme をOAuth に設定する必要があります。以下のセクションは、すでに設定済みであることを前提として書かれています。

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

CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成およびその理由については、カスタムOAuth アプリの作成を参照してください。

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

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

OAuthClientId（カスタムアプリのみ）：アプリケーションの登録時に割り当てられたクライアントId に設定。
OAuthClientSecret（カスタムアプリのみ）：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
CallbackURL（カスタムアプリのみ）：アプリケーションの登録時に定義されたリダイレクトURI に設定。

接続すると、本製品はデフォルトブラウザでHighrise のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。本製品はアクセストークンの期限が切れると自動的にリフレッシュします。

ヘッドレスマシン

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

以下のオプションから選択します。
- オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
- オプション2：インターネットブラウザに対応したマシンに本製品をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
次に、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品を設定します。

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

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

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

以下のオプションから選択します。
- 埋め込みOAuth アプリケーションを使用する場合は、GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
- カスタムOAuth アプリケーションを使用するには、以下のプロパティを設定します。
  - InitiateOAuth：OFF に設定。
  - OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
  - OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  次に、適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
ログインして、本製品にアクセス許可を与えます。すると、リダイレクトURI にリダイレクトされます。リダイレクトURI にはcode というパラメータが付加されます。このパラメータの値を控えておきます。後ほどこれをOAuthVerifier 接続プロパティに設定します。

次に、OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換する必要があります。

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

InitiateOAuth：REFRESH に設定。
OAuthVerifier：これを、控えておいたverifier code（リダイレクトURI のcode パラメータの値）に設定します。
OAuthClientId：（カスタムアプリのみ）カスタムOAuth アプリケーション設定のクライアントId に設定。
OAuthClientSecret：（カスタムアプリのみ）カスタムOAuth アプリケーション設定のクライアントシークレットに設定。
OAuthSettingsLocation：これを設定すると、暗号化されたOAuth 認証値が指定された場所に永続化されます。

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

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

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

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

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

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

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

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

API トークン

API トークンでHighrise へ認証するには、以下を設定します。

AuthScheme：AuthScheme をAPIToken に設定。
APIToken：ユーザーのAPIToken。 API トークンを取得するには、Highrise アカウントにログインしてMy Info のリンクをクリックします。管理者またはユーザーの場合、アカウントの"Settings" セクションにあります。詳しくは、Highrise ドキュメントのFind Your API Token を参照してください。
AccountId：ユーザーのAccount Id。

データの取得

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

$results = Select-Highrise -Connection $conn -Table "People" -Columns @("Id, Firstname") -Where "Id='MyId'"

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

cmdlet 出力のパイプ処理

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

Select-Highrise -Connection $conn -Table People -Where "Id = 'MyId'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myPeopleData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-Highrise -OAuthClientId 'MyOAuthClientId' -OAuthClientSecret 'MyOAuthClientSecret' -CallbackURL 'http://localhost' -AccountId 'MyAccountId'
PS C:\> $row = Select-Highrise -Connection $conn -Table "People" -Columns (Id, Firstname) -Where "Id = 'MyId'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "People",
  "Columns":  [

  ],
  "Id":  "MyId",
  "Firstname":  "MyFirstname"
}

データの削除

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

Select-Highrise -Connection $conn -Table People -Where "Id = 'MyId'" | Remove-Highrise

データの変更

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

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

Cmdlets for Highrise