接続の確立

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

インストールおよび接続

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

Install-Module SAPGatewayCmdlets

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

Import-Module SAPGatewayCmdlets;

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

$conn = Connect-SAPGateway -User "username" -Password "password" -URL "https://sapes5.sapdevcenter.com/sap/opu/odata/IWBEP/GWSAMPLE_BASIC/"

SAP Gateway への接続

SAP Gateway は、データに接続する2つの方法を提供します。

デスクトップ経由で自分のローカルデータに接続する場合（非ブラウザ接続、以下「Basic 認証」と呼ぶ）は、CData が提供する組み込みOAuth アプリケーションを使用します。
ネットワーク経由で共有データに接続する場合（ブラウザ接続）は、カスタムOAuth アプリケーションを使用します。

SAP Gateway のテーブルにアクセスするには、次の接続プロパティを設定します。

Url = お使いの環境のURL、またはサービスの完全URL。例えば、完全URL は次のようになります：https://sapes5.sapdevcenter.com/sap/opu/odata/IWBEP/GWSAMPLE_BASIC/。この例では、環境URL は次のようになります：https://sapes5.sapdevcenter.com。CustomUrlParams プロパティを使用して、追加プロパティを追加します。
Namespace = 適切なService Namespace。先ほどの例では、IWBEP が名前空間です。サービスへの完全URL が指定されている場合は任意です。
SAP Gateway = データを取得するサービス。先ほどの例では、サービスはGWSAMPLE_BASIC です。完全URL が指定されている場合は必須ではありません。
CustomUrlParams = HTTP リクエストに含まれる必要のある追加プロパティ；例えば sap-client=001&sap-language=EN。

SAP Gateway への認証

SAP Gateway はBasic 認証とOAuth 2.0 認証の両方を許可します。自分のアカウントに接続する場合はBasic 認証を使用し、共有データへの接続にはブラウザ経由のOAuth 認証を使用します。

Basic

Basic 認証を有効にするには、以下のプロパティを設定します。

AuthScheme = Basic。
User = SAP Gateway へのログインに使用するユーザー名。
Password = SAP Gateway へのログインに使用するパスワード。

上記のプロパティを設定したら、接続の準備は完了です。ローカルデータにアクセスするには、個人の認証情報を使用します。

OAuth

以下のサブセクションでは、デスクトップアプリケーション、Web、またはヘッドレスマシンから認証する方法を詳しく説明します。カスタムOAuth アプリケーションの作成については、カスタムOAuth アプリケーションの作成を参照してください。

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

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

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

OAuthClientId = アプリケーションの登録時に割り当てられたクライアントId。
OAuthClientSecret = アプリケーションの登録時に割り当てられたクライアントシークレット。
CallbackURL = アプリケーションの登録時に定義されたリダイレクトURI。

接続すると、本製品はデフォルトブラウザでSAP Gateway のOAuth エンドポイントを開きます。

ログインして、アプリケーションにアクセス許可を与えます。アクセストークンの期限が切れたときは、本製品はアクセストークンを自動でリフレッシュします。

ヘッドレスマシン

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

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

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

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

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

次のプロパティを設定します。
- 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 設定ファイルへのパス。アクセストークンの自動リフレッシュを有効にするために、このファイルが本製品に読み書きのアクセス許可を与えることを確認してください。

データの取得

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

$results = Select-SAPGateway -Connection $conn -Table "SampleTable_1" -Columns @("Id, Column1") -Where "Column2='Bob'"

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

cmdlet 出力のパイプ処理

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

Select-SAPGateway -Connection $conn -Table SampleTable_1 -Where "Column2 = 'Bob'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\mySampleTable_1Data.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-SAPGateway -User "username" -Password "password" -URL "https://sapes5.sapdevcenter.com/sap/opu/odata/IWBEP/GWSAMPLE_BASIC/"
PS C:\> $row = Select-SAPGateway -Connection $conn -Table "SampleTable_1" -Columns (Id, Column1) -Where "Column2 = 'Bob'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "SampleTable_1",
  "Columns":  [

  ],
  "Id":  "MyId",
  "Column1":  "MyColumn1"
}

データの削除

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

Select-SAPGateway -Connection $conn -Table SampleTable_1 -Where "Column2 = 'Bob'" | Remove-SAPGateway

データの変更

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

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

Cmdlets for SAP Gateway