接続の確立

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

このセクションでは、使用しているアカウントおよびサービスタイプの認証を提供し、接続する方法を説明します。

SAPByDesign Account の認証

SAP ByDesign に接続するには、次の接続プロパティを設定します。

分析サービスへの接続

URL：SAP ByDesign サイトのURL に設定。例：https://test.sapbydesign.com。
ServiceType：分析サービスのレポートを取得する場合はServiceType=AnalyticsService; を指定します。
ServiceName：データを取得するサービス名。指定しないか、1つのサービスのみ指定します。サービスのリストを指定したい場合は、BrowsableSchemas を参照してください。
指定するサービスがわからない場合は、sys_schemas をクエリして利用可能なサービスを一覧表示できます。
User：アカウントのユーザー名に設定。
Password：アカウントのパスワードに設定。

分析サービスの接続文字列の例：

Url=https://test.sapbydesign.com;ServiceType=AnalyticsService;ServiceName=cc_home_analytics.svc;User=Test;Password=test;

カスタムサービスへの接続

URL：SAP ByDesign サイトのURL に設定。例：https://test.sapbydesign.com。
ServiceType：データを取得するカスタムサービスがある場合はServiceType=CustomService; を指定します。
ServiceName：データを取得するサービス名。指定しないか、1つのサービスのみ指定します。サービスのリストを指定したい場合は、BrowsableSchemas を参照してください。
指定するサービスがわからない場合は、sys_schemas をクエリして利用可能なサービスを一覧表示できます。
User：アカウントのユーザー名に設定。
Password：アカウントのパスワードに設定。

カスタムサービスの接続文字列の例：

Url=https://test.sapbydesign.com;ServiceType=CustomService;ServiceName=khsalesorder;User=Test;Password=test;

ODataDataSource API への接続

URL：SAP ByDesign サイトのURL に設定。例：https://test.sapbydesign.com。
ServiceType：OData Data Source API (odata/analytics/ds) をクエリする場合は、ServiceType=ODataDataSource を指定します。
ServiceName：データを取得するサービス名。指定しないか、1つのサービスのみ指定します。サービスのリストを指定したい場合は、BrowsableSchemas を参照してください。
指定するサービスがわからない場合は、sys_schemas をクエリして利用可能なサービスを一覧表示できます。
User：アカウントのユーザー名に設定。
Password：アカウントのパスワードに設定。

ODataDataSource 接続文字列の例：

Url=https://test.sapbydesign.com;ServiceType=ODataDataSource;ServiceName=Customer.svc;User=Test;Password=test;

Azure AD による認証（SSO）

組織がMicrosoft Entra ID（旧Azure Active Directory）を使用してユーザーID を管理している場合、シングルサインオン（SSO）を使用してSAP ByDesign への認証を行うことができます。この方法では、ユーザーはユーザー名やパスワードを直接入力せずに接続できます。

Azure AD 認証を使用するには、以下の接続プロパティを設定します。

URL：SAP ByDesign サイトのURL に設定。
ServiceType：サービスのタイプを指定：AnalyticsService、CustomService、またはODataDataSource。
ServiceName：接続するサービス名に設定。
AuthScheme：AzureAD に設定。
InitiateOAuth：トークンの取得とリフレッシュを自動的に行うには、GETANDREFRESH に設定。
OAuthClientId：SAP ByDesign アプリケーションのOAuth クライアントID に設定。これはEntra ID アプリの登録とは別です。
SSOProperties：Azure AD 設定の詳細を含むセミコロン区切りの文字列。サポートされるキーについては、以下を参照してください。

Azure AD 接続文字列の例：

URL=https://my999999.businessbydesign.cloud.sap;
ServiceType=AnalyticsService;
ServiceName=cc_home_analytics.svc;
AuthScheme=AzureAD;
InitiateOAuth=GETANDREFRESH;
OAuthClientId=SAP_APP_CLIENT_ID;
SSOProperties='AzureTenant=TENANT_ID;OAuthClientId=AZURE_AD_APP_CLIENT_ID;OAuthClientSecret=AZURE_AD_CLIENT_SECRET;CallbackURL=http://localhost:33333'

サポートされるSSOProperties キー：

SSOProperties 接続プロパティには、Microsoft Entra ID（Azure AD）でのOAuth ベースの認証に必要なキーと値のペアのセミコロン区切りのリストが含まれます。これらのキーは、Entra ID がSSO のために実装しているOAuth 2.0 認可コードフローで使用されるフィールドに対応しています。本製品は、これらの値を使用して、Microsoft ID プラットフォームへの必要なリクエストを構築します。

AzureTenant：Entra ID（Azure AD）テナントID。GUID または検証済みドメインを使用できます。
OAuthClientId：Entra ID アプリ登録時のクライアントID。これはSAP アプリのクライアントID とは異なります。
OAuthClientSecret：Entra ID アプリのクライアントシークレット。
CallbackURL：（オプション）Entra ID に登録されているリダイレクトURI。デフォルトはhttp://localhost:33333 です。
Scope：（オプション）認証時にリクエストするOAuth スコープ。

Note：OAuthClientId の値は2つあります。

トップレベルのOAuthClientId は、SAP ByDesign に登録されているアプリを指します。
SSOProperties 内のOAuthClientId は、Microsoft Entra ID に登録されているアプリを指します。

Microsoft Entra ID アプリケーションの登録の詳細については、Entra ID（Azure AD）アプリケーションの作成を参照してください。

新しいカスタムODATA サービスを追加

SAP ByDesign ワークセンタービューで、［Application and User Management］をクリックします。
［OData Services］を選択します。
ドロップダウンリストから［Custom OData Services］を選択します。
これで現在のカスタムサービスのリストを見ることができます。新しいサービスを追加するには、［New］をクリックします。

SAP ByDesign URL の制約事項

SAP ByDesign 本製品は、許容されるURI の長さの上限を超えないようにURL に制限をかけており、これによりサービスは［URI Too Long］エラーをスローします。

デフォルトでは、プロジェクションのカラムの長さは1000文字に制限されています。プロジェクションで選択されたカラムがこの制限を超えると、ドライバーはプロジェクション指定を解除してすべてのフィールドを取得します。これは、サービスレスポンスの遅延やペイロードの増加により、パフォーマンスに影響を及ぼす可能性があります。

分析サービス（ServiceType =AnalyticsService）の場合、ドライバーはプロジェクションのカラム数を減らす必要があることを示すエラーを返します。また、サーバー側のフィルタの長さも同じ理由で1000文字に制限されています。生成されたフィルタの長さがこの制限を超える場合、ドライバーは追加のフィルタをドロップしてクライアントサイドで処理します。

SAP ByDesign で、MaxSelectLength およびMaxFilterLength 隠し接続プロパティを使用して、これらの制限を有効または無効にできます。これらのプロパティのデフォルトはいずれも1000文字です。サービスにこれらの制限がない場合は、プロパティを-1に設定して長さの制限を無効にしてください。

接続オブジェクトの作成

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

$conn = Connect-SAPByDesign -URL 'https://my999999.businessbydesign.cloud.sap' -User 'username' -Password 'password' -ServiceType 'AnalyticsService' -ServiceName 'servicename'

データの取得

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

$results = Select-SAPByDesign -Connection $conn -Table "Account" -Columns @("Id, Name") -Where "Industry='Floppy Disks'"

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

cmdlet 出力のパイプ処理

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

Select-SAPByDesign -Connection $conn -Table Account -Where "Industry = 'Floppy Disks'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myAccountData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-SAPByDesign -URL 'https://my999999.businessbydesign.cloud.sap' -User 'username' -Password 'password' -ServiceType 'AnalyticsService' -ServiceName 'servicename'
PS C:\> $row = Select-SAPByDesign -Connection $conn -Table "Account" -Columns (Id, Name) -Where "Industry = 'Floppy Disks'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Account",
  "Columns":  [

  ],
  "Id":  "MyId",
  "Name":  "MyName"
}

データの削除

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

Select-SAPByDesign -Connection $conn -Table Account -Where "Industry = 'Floppy Disks'" | Remove-SAPByDesign

データの変更

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

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

Cmdlets for SAP ByDesign