【ノーコード】SharePoint External Lists でPaylocity のデータにアクセス

古川えりか
古川えりか
コンテンツスペシャリスト
SharePointでのPaylocityデータアクセスでお困りですか？外部リスト機能で設定3ステップ、プログラミング不要でユーザー提供完了。無償トライアルですぐにスタート。



本記事で紹介している手法は、2023年現在ご利用いただけなくなっております。SharePoint リストへの外部データの連携については、以下の記事の方法をご確認ください。

CData Arc を使ってSQL Server のデータをSharePoint Online のリストにノーコードで連携

CData API Server およびADO.NET Provider for Paylocity (または他の250+ ADO.NET Providers) を組み合わせて利用することで、SharePoint でPaylocity にアクセス および更新することができます。 この記事では、常に最新状態のPaylocity を外部リクエストとして作成する方法を説明します。外部コンテンツタイプをテンプレートとして使用し、外部リストを作成します。外部コンテンツタイプは、モバイルおよびその他のオンラインアプリケーション用のリアルタイムデータストリーミングプロトコルであるOData を介した接続を可能にします。API Server は、Paylocity フィードのOData プロデューサーです。

API Server を設定した後、Paylocity に接続できる外部リストの作成方法は、以下の基本的な3つのステップによって構成されます。

  1. 外部コンテンツタイプの作成
  2. 外部コンテンツタイプをインポート
  3. 外部リストの作成

この記事は、以下のタスクを実行する方法についても説明します。

API Server の設定

以下のリンクからAPI Server の無償トライアルをスタートしたら、セキュアなPaylocity OData サービスを作成していきましょう。

Paylocity への接続

Salesforce Connect からPaylocity のデータを操作するには、まずPaylocity への接続を作成・設定します。

  1. API Server にログインして、「Connections」をクリック、さらに「接続を追加」をクリックします。 接続を追加
  2. 「接続を追加」をクリックして、データソースがAPI Server に事前にインストールされている場合は、一覧から「Paylocity」を選択します。
  3. 事前にインストールされていない場合は、コネクタを追加していきます。コネクタ追加の手順は以下の記事にまとめてありますので、ご確認ください。
    CData コネクタの追加方法はこちら >>
  4. それでは、Paylocity への接続設定を行っていきましょう！ 接続設定

  5. Paylocity への接続を確立するには以下を設定します。

    • RSAPublicKey：Paylocity アカウントでRSA 暗号化が有効になっている場合は、Paylocity に関連付けられたRSA キーを設定。

      このプロパティは、Insert およびUpdate ステートメントを実行するために必須です。この機能が無効になっている場合は必須ではありません。

    • UseSandbox：サンドボックスアカウントを使用する場合はTrue に設定。
    • CustomFieldsCategory：Customfields カテゴリに設定。これは、IncludeCustomFields がtrue に設定されている場合は必須です。デフォルト値はPayrollAndHR です。
    • Key：Paylocity の公開鍵で暗号化されたAES 共通鍵（base 64 エンコード）。これはコンテンツを暗号化するためのキーです。

      Paylocity は、RSA 復号化を使用してAES 鍵を復号化します。
      これはオプションのプロパティで、IV の値が指定されていない場合、ドライバーは内部でキーを生成します。

    • IV：コンテンツを暗号化するときに使用するAES IV（base 64 エンコード）。これはオプションのプロパティで、Key の値が指定されていない場合、ドライバーは内部でIV を生成します。

    OAuth

    OAuth を使用してPaylocity で認証する必要があります。OAuth では認証するユーザーにブラウザでPaylocity との通信を要求します。詳しくは、ヘルプドキュメントのOAuth セクションを参照してください。

    Pay Entry API

    Pay Entry API はPaylocity API の他の部分と完全に分離されています。個別のクライアントID とシークレットを使用し、アカウントへのアクセスを許可するにはPaylocity から明示的にリクエストする必要があります。 Pay Entry API を使用すると、個々の従業員の給与情報を自動的に送信できます。 Pay Entry API によって提供されるものの性質が非常に限られているため、CData では個別のスキーマを提供しないことを選択しましたが、UsePayEntryAPI 接続プロパティを介して有効にできます。

    UsePayEntryAPI をtrue に設定する場合は、CreatePayEntryImportBatch、MergePayEntryImportBatch、Input_TimeEntry、およびOAuth ストアドプロシージャのみ利用できることに注意してください。 製品のその他の機能を使用しようとするとエラーが発生します。また、OAuthAccessToken を個別に保存する必要があります。これは、この接続プロパティを使用するときに異なるOAuthSettingsLocation を設定することを意味します。

  6. 接続情報の入力が完了したら、「保存およびテスト」をクリックします。

Paylocity への接続を確立するには以下を設定します。

  • RSAPublicKey：Paylocity アカウントでRSA 暗号化が有効になっている場合は、Paylocity に関連付けられたRSA キーを設定。

    このプロパティは、Insert およびUpdate ステートメントを実行するために必須です。この機能が無効になっている場合は必須ではありません。

  • UseSandbox：サンドボックスアカウントを使用する場合はTrue に設定。
  • CustomFieldsCategory：Customfields カテゴリに設定。これは、IncludeCustomFields がtrue に設定されている場合は必須です。デフォルト値はPayrollAndHR です。
  • Key：Paylocity の公開鍵で暗号化されたAES 共通鍵（base 64 エンコード）。これはコンテンツを暗号化するためのキーです。

    Paylocity は、RSA 復号化を使用してAES 鍵を復号化します。
    これはオプションのプロパティで、IV の値が指定されていない場合、ドライバーは内部でキーを生成します。

  • IV：コンテンツを暗号化するときに使用するAES IV（base 64 エンコード）。これはオプションのプロパティで、Key の値が指定されていない場合、ドライバーは内部でIV を生成します。

OAuth

OAuth を使用してPaylocity で認証する必要があります。OAuth では認証するユーザーにブラウザでPaylocity との通信を要求します。詳しくは、ヘルプドキュメントのOAuth セクションを参照してください。

Pay Entry API

Pay Entry API はPaylocity API の他の部分と完全に分離されています。個別のクライアントID とシークレットを使用し、アカウントへのアクセスを許可するにはPaylocity から明示的にリクエストする必要があります。 Pay Entry API を使用すると、個々の従業員の給与情報を自動的に送信できます。 Pay Entry API によって提供されるものの性質が非常に限られているため、CData では個別のスキーマを提供しないことを選択しましたが、UsePayEntryAPI 接続プロパティを介して有効にできます。

UsePayEntryAPI をtrue に設定する場合は、CreatePayEntryImportBatch、MergePayEntryImportBatch、Input_TimeEntry、およびOAuth ストアドプロシージャのみ利用できることに注意してください。 製品のその他の機能を使用しようとするとエラーが発生します。また、OAuthAccessToken を個別に保存する必要があります。これは、この接続プロパティを使用するときに異なるOAuthSettingsLocation を設定することを意味します。

API Server のユーザー設定

次に、API Server 経由でPaylocity にアクセスするユーザーを作成します。「Users」ページでユーザーを追加・設定できます。やってみましょう。

  1. 「Users」ページで ユーザーを追加をクリックすると、「ユーザーを追加」ポップアップが開きます。
  2. 次に、「ロール」、「ユーザー名」、「権限」プロパティを設定し、「ユーザーを追加」をクリックします。
  3. その後、ユーザーの認証トークンが生成されます。各ユーザーの認証トークンとその他の情報は「Users」ページで確認できます。

Paylocity 用のAPI エンドポイントの作成

ユーザーを作成したら、Paylocity のデータ用のAPI エンドポイントを作成していきます。

  1. まず、「API」ページに移動し、 「 テーブルを追加」をクリックします。
  2. アクセスしたい接続を選択し、次へをクリックします。
  3. 接続を選択した状態で、各テーブルを選択して確認をクリックすることでエンドポイントを作成します。

OData のエンドポイントを取得

以上でPaylocity への接続を設定してユーザーを作成し、API Server でPaylocity データのAPI を追加しました。これで、OData 形式のPaylocity データをREST API で利用できます。API Server の「API」ページから、API のエンドポイントを表示およびコピーできます。

Paylocity への接続を確立するには以下を設定します。

  • RSAPublicKey：Paylocity アカウントでRSA 暗号化が有効になっている場合は、Paylocity に関連付けられたRSA キーを設定。

    このプロパティは、Insert およびUpdate ステートメントを実行するために必須です。この機能が無効になっている場合は必須ではありません。

  • UseSandbox：サンドボックスアカウントを使用する場合はTrue に設定。
  • CustomFieldsCategory：Customfields カテゴリに設定。これは、IncludeCustomFields がtrue に設定されている場合は必須です。デフォルト値はPayrollAndHR です。
  • Key：Paylocity の公開鍵で暗号化されたAES 共通鍵（base 64 エンコード）。これはコンテンツを暗号化するためのキーです。

    Paylocity は、RSA 復号化を使用してAES 鍵を復号化します。
    これはオプションのプロパティで、IV の値が指定されていない場合、ドライバーは内部でキーを生成します。

  • IV：コンテンツを暗号化するときに使用するAES IV（base 64 エンコード）。これはオプションのプロパティで、Key の値が指定されていない場合、ドライバーは内部でIV を生成します。

OAuth

OAuth を使用してPaylocity で認証する必要があります。OAuth では認証するユーザーにブラウザでPaylocity との通信を要求します。詳しくは、ヘルプドキュメントのOAuth セクションを参照してください。

Pay Entry API

Pay Entry API はPaylocity API の他の部分と完全に分離されています。個別のクライアントID とシークレットを使用し、アカウントへのアクセスを許可するにはPaylocity から明示的にリクエストする必要があります。 Pay Entry API を使用すると、個々の従業員の給与情報を自動的に送信できます。 Pay Entry API によって提供されるものの性質が非常に限られているため、CData では個別のスキーマを提供しないことを選択しましたが、UsePayEntryAPI 接続プロパティを介して有効にできます。

UsePayEntryAPI をtrue に設定する場合は、CreatePayEntryImportBatch、MergePayEntryImportBatch、Input_TimeEntry、およびOAuth ストアドプロシージャのみ利用できることに注意してください。 製品のその他の機能を使用しようとするとエラーが発生します。また、OAuthAccessToken を個別に保存する必要があります。これは、この接続プロパティを使用するときに異なるOAuthSettingsLocation を設定することを意味します。

SharePoint はOData 3.0 データソースに対応しています。［Settings］->［Server］をクリックし、［デフォルトのOData バージョン］メニューで［OData 3.0］を選択してください。

外部コンテンツタイプを作成

外部コンテンツタイプとは、SharePoint アプリからPaylocity へのコア接続を提供するスキーマです。任意のOData クエリのスキーマを作成できます。$sharepoint クエリ文字列パラメータを使用して、必要なオプションを渡すことができます。以下は、.ect ファイルでスキーマを返すリクエストの例です。 

https://my-server:8032/api.rsc/Employee?$sharepoint=AuthMode:Passthrough&@authtoken=my-authtoken

簡単にするために、authtoken はクエリ文字列で渡され、.ect のリクエストを認証することに注意してください。これはデフォルトでは有効になっていないため、この方法を使用してAPI Server への認証を行う場合は、settings.cfg ファイルに次のようなエントリを追加する必要があります。 

[Application]
AllowAuthtokenInUrl = true

settings.cfg ファイルはデータディレクトリにあります。.NET エディションでは、データディレクトリはアプリケーションルートのapp_data サブフォルダにあります。Java エディションでは、データディレクトリの場所はオペレーティングシステムによって異なります。

  • Windows:C:\ProgramData\CData
  • Unix or Mac OS X: ~/cdata

外部コンテンツタイプをインポート

.ect を作成したら、以下のステップに従って、SharePoint Online またはオンプレミスのSharePoint インストールにインポートできます。

SharePoint 2013

SharePoint サーバーの全体管理ポータルに移動し、リンクをクリックしてサービスアプリケーションを管理します。 表示されるページで［Business Data Connectivity Service］をクリックします。メニューで［External Content Types］を選択し、［Import］をクリックします。［BDC Model］セクションで［Choose File］をクリックし、ダイアログで.ect ファイルを選択します。

SharePoint Online

SharePoint 管理センターで、クイック起動メニューから［BCS］をクリックし、［Manage BDC Models and External Content Types］をクリックします。表示されるページのメニューで［External Content Types］を選択し、［Import］をクリックします。［BDC Model］セクションで［Choose File］をクリックます。

外部リストを作成

Paylocity へのアクセスと変更が可能なSharePoint アプリを作成できます。

  1. SharePoint サイトに移動し、［Site Contents］->［Add an App］->［External List］と進みます。
  2. ［Select External Content］をクリックします。 アイコンを入力し、前のセクションで作成した外部コンテンツタイプを選択します。
  3. ［Create］をクリックします。
The external list.(Salesforce with SharePoint 2013 is shown.)

結果をリミット

SharePoint には、OData ソースの外部リストから取得できるデータの量にリミットがあります。外部リストは、デフォルトで30 項目のページに結果を表示します。ページングサイズを変更するには、デフォルトビューの設定で［Item Limit］プロパティを設定できます。もしくはカスタムWeb パーツを作成し、外部リストのデータを表示することもできます。

SharePoint 2013 では、外部データソースへの要求は、バンドのスロットルコントロールによって制限されます。これは、Set-SPBusinessDataCatalogThrottleConfig コマンドを実行します。SharePoint Online では、外部データソースへの要求がServer Resource Quota とスロットルコントロールによって制限されます。これを回避するためにデータのリクエストにフィルタを適用できます。

API Server は、返される行数のデフォルトの制限を500 に設定します。$sharepoint クエリ文字列パラメータにlimit オプションを追加し、その値を0 に設定することで、この制限を無効にできます。

パススルー認証を構成

外部コンテンツタイプにアクセスするためにパススルー認証を使用するには、AuthMode オプションをパススルーに設定します。

Kerberos 認証を使用している場合は、これらのユーザーをAPI Server に追加する必要があります。 Kerberos 認証を使用していない場合は、NTLM などの別の形式のWindows 認証を使用している可能性があります。

ユーザーがNTLM 認証を介して認証し、SharePoint のBusiness Connectivity Service (BCS) でパススルー認証を使用している場合、SharePoint はデフォルトのIIS アカウントを使用して外部Web サービスに接続します。 このアカウントは、多くの場合NT AUTHORITY\IUSR アカウントです。 このユーザーにCData API Server へのアクセスを許可します。

API Server でWindows 認証を有効にするためのガイドについては、ヘルプドキュメントを参照してください。

資格情報認証の構成

次のセクションでは、はじめにAPI Server に追加されたユーザーの資格情報を使用し、API Server に対してSharePoint ユーザーを認証するセキュアストアターゲットアプリケーションを作成します。次に、外部コンテンツタイプを作成し、セキュアストアの資格情報で認証するように構成します。

SharePoint Online

  1. SharePoint Online 管理センターで、クイック起動バーから［secure store］をクリックし、［New］をクリックします。
  2. ［Target Application Settings］セクションで、ターゲットアプリケーションId、表示名、連絡先の電子メールを入力します。
  3. ［Credential Fields］セクションで、API Server の資格情報を追加します。
  4. ［Target Application Administrators］セクションで、外部コンテンツタイプの接続設定にアクセスできる管理者を選択します。［SharePoint Online］の管理者アカウントは、通常ここで指定されます。 administrator is usually specified here.
  5. ［Members］セクションでPaylocity へのアクセスを許可されているSharePoint のユーザーを入力します。 The configuration page for the new target application in SharePoint Online.(Salesforce is shown.)

ターゲットアプリケーションを作成したら、API Server ユーザーの資格情報をセキュアストアに保存します。

  1. クイック起動バーで［secure store］をクリックします。
  2. ターゲットアプリケーションのメニューで［Set Credentials］をクリックします。
  3. API Server にユーザーのユーザー名とパスワードを入力します。

次に、新しい接続設定オブジェクトを作成します。

  1. クイック起動バーから［BCS］をクリックし、オンラインサービスへの接続を管理するオプションを選択します。
  2. ［Add］をクリックします。接続に名前を付け、OData エンドポイントのURL (https://my-server/api.rsc) を入力します。
  3. SharePoint に保存されている資格情報を使用するオプションを選択します。作成したターゲットアプリケーションのアプリケーションId を入力します。

最後に、外部コンテンツタイプを作成し、SharePoint Online にインポートして外部リストを作成します。

  1. データを要求し、$sharepoint クエリ文字列パラメータで必要なオプションを指定して外部コンテンツタイプを生成します。AuthMode オプションをCredentials に設定します。ターゲットアプリケーションId と接続設定オブジェクトのId を指定します。例： 
    https://my-server/api.rsc/Employee?$filter=EmployeeId eq '1234'&$sharepoint=AuthMode:Credentials,TargetApplicationId:my-target-application-Id,ODataConnectionSettingsId:my-odata-connection-settings-Id
  2. 結果の.ect ファイルをインポートします。クイック起動バーからBCS を開き、リンクをクリックしてBDC モデルと外部コンテンツタイプを管理します。［Import］をクリックします。
  3. 外部リストを作成できます。

SharePoint 2013

  1. SharePoint サイトの中央管理領域を参照し、リンクをクリックしてサービスアプリケーションを管理します。
  2. ［Secure Store Service］をクリックし、［New］をクリックします。
  3. アプリケーションId、表示名、連絡先の電子メールを入力し、新しいセキュアストアターゲットアプリケーションを構成します。ターゲットアプリケーションタイプをGroup に設定します。 Creating a new target application in SharePoint 2013.(Salesforce is shown.)
  4. 次のページで、ユーザーがユーザー名とパスワードを入力したときに表示するフィールド名とフィールドタイプを追加します。ユーザー名とパスワードのフィールドタイプを選択します。 The type of authentication used for the API Server.
  5. 次に、［Target Application Administrators］セクションで、外部コンテンツタイプの接続設定へのアクセスを許可されている管理者を選択します。 ［Members］セクションでAPI Server ユーザーの資格情報との接続を許可されているSharePoint のユーザーを入力します。 Administrators of the external content type and SharePoint users who are authorized to use the API Server.

新しいセキュアストアターゲットアプリケーションを作成したら、以下のステップに従ってSharePoint のユーザーがAPI Server にアクセスするときに提供する資格情報を設定します。

  1. ターゲットアプリケーションのメニューで［Set Credentials］をクリックします。 The first step to save credentials to the API Server in the secure store.(Salesforce is shown.)
  2. 表示されるメニューでAPI Server ユーザーのユーザー名とパスワード(authtoken) を入力します。 The credentials of a user in the API Server.(Salesforce is shown.)

  3. SharePoint 管理シェルのインスタンスを開き、新しいSharePoint 接続オブジェクトを初期化します。接続オブジェクトはサイト固有のものであることに注意してください。 

    New-SPODataConnectionSetting -AuthenticationMode Credentials -ServiceAddressURL http://my-server/api.rsc -ServiceContext http://myspsite/ -Name MyODataConnectionSettingsId -SecureStoreTargetApplicationId my-target-application-Id

    以下の出力は、コマンドが正常に実行されたことを示しています。

    The initialized connection object.

最後のステップでは、SharePoint で公開するテーブルの外部コンテンツタイプを作成し、セキュアストアからの資格情報で認証するように構成してからSharePoint にインポートします。

  1. データを要求し、$sharepoint クエリ文字列パラメータで必要なオプションを指定して外部コンテンツタイプを生成します。 以下はリクエストの一例です。 
    http://my-server/api.rsc/Account?$filter=Industry eq 'Floppy Disks'&$sharepoint=AuthMode:Credentials,TargetApplicationId:my-target-application-Id,ODataConnectionSettingsId:my-odata-connection-settings-Id
  2. 外部コンテンツタイプをSharePoint にインポートするには、ブラウザでSharePoint 中央管理ポータルをインストールし、リンクをクリックしてサービスアプリケーションを管理します。
  3. 表示されるページで［Business Data Connectivity Service］をクリックします。
  4. ［Import］をクリックし、ダイアログで.ect ファイルを選択します。
  5. これで、外部リストを作成できます。SharePoint サイトの［Site Contents］ページでボタンをクリックしてアプリを追加し、アイコンをクリックして外部コンテンツタイプを選択します。

はじめる準備はできましたか？

詳細はこちら、または無料トライアルにお申し込みください：

CData API Server お問い合わせ

この記事の内容

関連記事