接続の確立

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

インストールおよび接続

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

Install-Module PaylocityCmdlets

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

Import-Module PaylocityCmdlets;

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

$conn = Connect-Paylocity -InitiateOauth "GETANDREFRESH" -OAuthClientID "YourClientId" -OAuthClientSecret "YourClientSecret" -RSAPublicKey "YourRSAPubKey" -Key "YourKey" -IV "YourIV"

Paylocity への接続

Paylocity は、Pay Entry API 経由と標準のPaylocity API 経由の2つの接続方法を提供します。

接続する前に、次のプロパティを設定します（該当する場合）。

サンドボックスアカウントを使用する場合はUseSandbox をtrue に設定し、そうでない場合はfalse に設定します。
IncludeCustomFields がtrue の場合、CustomFieldsCategory をCustomfields カテゴリに設定します。デフォルト値はPayrollAndHR です。

暗号化をオプトインしているサイトの場合：

次の暗号化プロパティのいずれか1つだけを設定してください。
- Key：Paylocity の公開鍵で暗号化されたAES 共通鍵（base 64 エンコード）。この鍵はPaylocity コンテンツの暗号化に使用されます。Paylocity はRSA 復号化を使用してAES 鍵を復号化します。
  IV 値が指定されていない場合に使用されます。
- IV：Paylocity を暗号化するときに使用するAES IV（base 64 エンコード）。Key 値が提供されない場合は、IV は内部的に生成されます。
Paylocity アカウントでRSA 暗号化が有効になっている場合は、RSAPublicKey をPaylocity に関連付けられたRSA キーに設定します。（このプロパティは、Insert およびUpdate ステートメントを実行する場合は必須です。）この機能が無効になっている場合は必須ではありません。

Pay Entry API

Pay Entry API は、個々の従業員の給与情報を自動的に提出することを可能にする、極めて限定的な接続であり、それ以外のことはほとんどできません。Pay Entry API で提供されるものは極めて限定されているため、独立したスキーマはありません。しかし、UsePayEntryAPI 接続プロパティで有効にすることができます。

Pay Entry API はPaylocity API の他の部分と完全に分離されています。個別のクライアントID とシークレットを使用し、アカウントへのアクセスを許可するにはPaylocity から明示的にリクエストする必要があります。

UsePayEntryAPI をtrue に設定する場合は、以下のストアドプロシージャのみ利用できることに注意してください。

CreatePayEntryImportBatch
MergePayEntryImportBatch
Input_TimeEntry
利用可能なOAuth ストアドプロシージャ

製品のその他の機能を使用しようとするとエラーが発生します。

また、Pay Entry API で使用するために取得したOAuthAccessToken は、別途保存する必要があります。このため、この接続プロパティを使用する際には、別のOAuthSettingsLocation の設定が必要になることがよくあります。

Paylocity への認証

Paylocity は、Pay Entry API または標準のPayloticity API からのデータへのすべての接続でOAuth 認証をサポートします。この認証を有効にするには、すべてのOAuth フローでAuthScheme をOAuth に設定し、カスタムOAuth アプリケーションを作成する必要があります。

以下のサブセクションでは、3つの最も一般的な認証フローでのPaylocity への認証について詳しく説明します。カスタムOAuth アプリケーションの作成については、カスタムOAuth アプリケーションの作成を参照してください。 Paylocity で利用可能な接続文字列プロパティの全リストは、Connection を参照してください。

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

カスタムOAuth アプリケーションの資格情報を使用して認証するには、OAuth アクセストークンを取得し、更新する必要があります。これらを設定すると、接続の準備が整います。

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

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

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

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

OAuth アクセストークンの自動リフレッシュ：

本製品がOAuth アクセストークンを自動的にリフレッシュするようにするには、次のように設定します。

はじめてデータに接続する前に、次の接続プロパティを設定します。
- InitiateOAuth = REFRESH。
- OAuthClientId = アプリケーション設定のクライアントId。
- OAuthClientSecret = アプリケーション設定のクライアントシークレット。
- OAuthAccessToken = GetOAuthAccessToken によって返されたアクセストークン。
- OAuthSettingsLocation = 本製品がOAuth 値を保存する場所のパス。これは接続間で維持されます。
その後のデータ接続では、以下を設定します。
- InitiateOAuth
- OAuthSettingsLocation

OAuth アクセストークンの手動リフレッシュ：

OAuth アクセストークンを手動でリフレッシュするために必要な唯一の値は、OAuth リフレッシュトークンです。

ExpiresIn 期間（GetOAuthAccessToken が返す）が経過した後にOAuthAccessToken を手動でリフレッシュするには、RefreshOAuthAccessToken ストアドプロシージャを呼び出します。
次の接続プロパティを設定します。
- OAuthClientId = アプリケーション設定のクライアントId。
- OAuthClientSecret = アプリケーション設定のクライアントシークレット。
RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを設定します。
新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定します。これで新規接続が開かれます。

OAuth リフレッシュトークンを保存し、OAuth アクセストークンの有効期限が切れた後に手動でリフレッシュできるようにします。

ヘッドレスマシン

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

オプション1：OAuthVerifier 値を取得します。
オプション2：インターネットブラウザに対応したマシンに本製品をインストールし、通常のブラウザベースのフローで認証した後でOAuth 認証値を転送します。

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

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

Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。以下の手順に従います。

インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得します。

次のプロパティを設定します。
- InitiateOAuth = OFF。
- OAuthClientId = アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret = アプリケーションの登録時に割り当てられたクライアントシークレット。
カスタムOAuth アプリケーションの登録時に定義したCallbackURL を取得します。（カスタムOAuth アプリケーションの作成を参照してください。）新しいブラウザのタブにこのURL を貼り付けます。
ログインして、本製品にアクセス許可を与えます。OAuth アプリケーションは、code というパラメータを付加したリダイレクトURI にリダイレクトします。このパラメータの値を控えておきます。OAuthVerifier 接続プロパティを設定するために、後で必要になります。
OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換します。ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。
- InitiateOAuth = REFRESH。
- OAuthVerifier = 控えておいたverifier code（リダイレクトURI のcode パラメータの値）。
- OAuthSettingsLocation = 暗号化されたOAuth 認証値を指定されたファイルに永続化。
- OAuthClientId = カスタムOAuth アプリケーション設定のクライアントId。
- OAuthClientSecret = カスタムOAuth アプリケーション設定のクライアントシークレット。
接続をテストしてOAuth 設定ファイルを生成します。
次のプロパティを再設定して、接続してください。
- InitiateOAuth = REFRESH。
- OAuthSettingsLocation = 暗号化されたOAuth 認証値を含むファイル。アクセストークンの自動リフレッシュを有効にするには、このファイルが本製品に読み書きのアクセス許可を与えることを確認してください。
- OAuthClientId = アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret = アプリケーションの登録時に割り当てられたクライアントシークレット。

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

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

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

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

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

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

データの取得

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

$results = Select-Paylocity -Connection $conn -Table "Employee" -Columns @("FirstName, LastName") -Where "EmployeeId='1234'"

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

cmdlet 出力のパイプ処理

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

Select-Paylocity -Connection $conn -Table Employee -Where "EmployeeId = '1234'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myEmployeeData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-Paylocity -InitiateOauth "GETANDREFRESH" -OAuthClientID "YourClientId" -OAuthClientSecret "YourClientSecret" -RSAPublicKey "YourRSAPubKey" -Key "YourKey" -IV "YourIV"
PS C:\> $row = Select-Paylocity -Connection $conn -Table "Employee" -Columns (FirstName, LastName) -Where "EmployeeId = '1234'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Employee",
  "Columns":  [

  ],
  "FirstName":  "MyFirstName",
  "LastName":  "MyLastName"
}

データの削除

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

Select-Paylocity -Connection $conn -Table Employee -Where "EmployeeId = '1234'" | Remove-Paylocity

データの変更

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

Import-Csv -Path C:\MyEmployeeUpdates.csv | %{
  $record = Select-Paylocity -Connection $conn -Table Employee -Where ("EmployeeId = `'"+$_.EmployeeId+"`'")
  if($record){
    Update-Paylocity -Connection $conn -Table Employee -Columns @("FirstName","LastName") -Values @($_.FirstName, $_.LastName) -Where "EmployeeId  = `'$_.EmployeeId`'"
  }else{
    Add-Paylocity -Connection $conn -Table Employee -Columns @("FirstName","LastName") -Values @($_.FirstName, $_.LastName)
  }
}

Cmdlets for Paylocity