接続の確立

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

Wave Financial への接続

Wave Financial は、データに接続する手段として、API トークンを指定する方法とOAuth 認証情報を使用する方法の2つを提供しています。

API トークン

Wave Financial API トークンを取得するには：

Wave Financial アカウントにログインします。
左ペインのManage Applications に移動します。
トークンを作成するアプリケーションを選択します。最初にアプリケーションを作成する必要がある場合があります。
API トークンを生成するには、Create token をクリックします。

OAuth

Wave Financial はOAuth 認証のみサポートします。すべてのOAuth フローで、この認証を有効にするにはAuthScheme をOAuth に設定する必要があります。

以下のサブセクションでは、3つの一般的な認証フローでのWave Financial への認証について詳しく説明します。

デスクトップ：ユーザーのローカルマシン上でのサーバーへの接続で、テストやプロトタイピングによく使用されます。組み込みOAuth またはカスタムOAuth で認証されます。
Web：共有ウェブサイト経由でデータにアクセスします。カスタムOAuth でのみ認証されます。
ヘッドレスサーバー：他のコンピュータやそのユーザーにサービスを提供する専用コンピュータで、モニタやキーボードなしで動作するように構成されています。組み込みOAuth またはカスタムOAuth で認証されます。

カスタムOAuth アプリケーションの作成についての情報と、組み込みOAuth 認証情報を持つ認証フローでもカスタムOAuth アプリケーションを作成したほうがよい場合の説明については、カスタムOAuth アプリケーションの作成を参照してください。

Wave Financial で利用可能な接続文字列プロパティの全リストは、Connection を参照してください。

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

CData は、デスクトップでの認証を簡単にする組み込みOAuth アプリケーションを提供します。また、Wave Financial コンソールで設定および登録するカスタムOAuth アプリケーションを介してデスクトップから認証することもできます。詳しくは、カスタムOAuth アプリケーションの作成を参照してください。

接続の前に、以下の変数を設定します。

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

接続すると、本製品はデフォルトブラウザでWave Financial の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 によって返された値を設定します。Open は、新規接続を開きます。

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

ヘッドレスマシン

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

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

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

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

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

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

組み込みOAuth アプリケーションを使用する場合は、GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。

カスタムOAuth アプリケーションを使用するには、以下のプロパティを設定します。
- InitiateOAuth = OFF。
- OAuthClientId = アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret = アプリケーションの登録時に割り当てられたクライアントシークレット。
GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャは、カスタムOAuth アプリケーションが登録されたときに構築されたCallbackURL を返します。（カスタムOAuth アプリケーションの作成を参照してください。）

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

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

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

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

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

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

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

接続オブジェクトの作成

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

$conn = Connect-WaveFinancial -InitiateOAuth "GETANDREFRESH"

データの取得

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

$results = Select-WaveFinancial -Connection $conn -Table "Invoices" -Columns @("Id, DueDate") -Where "Status='SENT'"

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

cmdlet 出力のパイプ処理

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

Select-WaveFinancial -Connection $conn -Table Invoices -Where "Status = 'SENT'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myInvoicesData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-WaveFinancial -InitiateOAuth "GETANDREFRESH"
PS C:\> $row = Select-WaveFinancial -Connection $conn -Table "Invoices" -Columns (Id, DueDate) -Where "Status = 'SENT'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Invoices",
  "Columns":  [

  ],
  "Id":  "MyId",
  "DueDate":  "MyDueDate"
}

Cmdlets for Wave Financial