このセクションでは、以下のいくつかのLinux ディストリビューションでODBC 接続をセットアップしDSN を設定する方法を説明します：Ubuntu のようなDebian ベースのシステム、Red Hat Enterprise Linux (RHEL)、およびFedora のようなRed Hat Linux プラットフォーム。

Linux の最小バージョン

Red Hat ベースおよびDebian ベースシステムでサポートされる最小バージョンは以下のとおりです。

OS	Min. Version
Ubuntu	18.04
Debian	10
RHEL	8
Fedora	28
SUSE	15

ドライバー依存関係のインストール

必要な依存関係をインストールするには、次のコマンドをルートとしてまたはsudo で実行します。

• Debian/Ubuntu:
  

  apt-get install libc6 libstdc++6 zlib1g libgcc1

• RHEL/Fedora:
  

  yum install glibc libstdc++ zlib libgcc

ドライバーのインストール

標準のパッケージ管理システムを使用してドライバーをインストールできます。

Ubuntu のようなDebian ベースのシステムでは、次のコマンドをroot またはsudo で実行します。

dpkg -i /path/to/driver/setup/PowerBIXMLAODBCDriverforUnix.deb 

RPM パッケージ形式をサポートするシステムでは、次のコマンドをroot またはsudo で実行します。

rpm -ivh /path/to/driver/PowerBIXMLAODBCDriverforUnix.rpm 

ドライバーのライセンス

次のコマンドを実行して本製品 のライセンスを取得します。評価版をアクティベートするには、<key> の入力を省略してください。

cd /opt/cdata/cdata-odbc-driver-for-powerbixmla/bin/
sudo ./install-license.sh <key>

ドライバーマネージャー経由の接続

ドライバーマネージャーはドライバーをロードし、アプリケーションからドライバーに関数呼び出しを渡します。本製品 をドライバーマネージャーに登録して、ドライバーマネージャーのコンフィギュレーションファイルにDSN を定義する必要があります。

本製品 のインストールでは、本製品 をunixODBC ドライバーマネージャーに登録し、システムDSN を作成します。UnixODBC ドライバーマネージャーは、Python やその他多くのアプリケーションから使用できます。アプリケーションに別のドライバーマネージャーが組み込まれている可能性があります。

DSN の作成

unixODBC をインストールしてDSN を設定するには、unixODBC の使用 を参照してください。OBIEE、Informatica、およびSAS に接続するDSN を作成するには、DataDirect ドライバーマネージャーの使用 を参照してください。

Microsoft Power BI XMLA への接続

Microsoft Power BI XMLA への接続を確立するには、主に3つのステップがあります。

1. ご利用の環境に応じて、適切な認証方法を選択します。
2. 必要な接続プロパティ（トークン、シークレット、証明書など）を設定します。
3. 対象のPower BI ワークスペースを設定します。

重要： Power BI Premium 容量でホストされているワークスペースのみがサポートされます。 ワークスペースがPremium 容量でない場合、接続は失敗します。これをPower BI で確認するには、ブラウザでワークスペースを開き、ワークスペース名の横にあるダイヤモンドのアイコンを探してください。 これは、Premium 容量に対応したワークスペースを識別するための、Power BI ユーザーインターフェースに組み込まれたインジケータです。アイコンが表示されていない場合、そのワークスペースはXMLA 接続に対応していません。詳細はPower BI ライセンスの種類 を参照してください。

ステップ1：認証方法の選択

AuthScheme プロパティを設定して、導入シナリオに適した認証フローを選択してします。サポートされている値には、次のものが含まれます。

• AzureAD – 対話型のユーザーベースのログインフロー向け。
  • デスクトップアプリケーション、開発環境、またはユーザーがブラウザを介して認証するシナリオに最適です。
  • 組み込みOAuth アプリケーションをサポートし、セットアップを簡素化します。ただし、組織で高度なセキュリティポリシーが必要な場合や、登録済みのリダイレクトURI が必要なWeb ベースのソリューションを展開する場合は、代わりにカスタムアプリを使用してください。
  • この認証方法を使用するためにカスタムOAuth アプリケーションを登録するには、Entra ID（Azure AD）アプリケーションの作成 を参照してください。
• AzureServicePrincipal – クライアントID とシークレットを使用した、ヘッドレスなサービス間認証向け。
  • CI/CD パイプライン、バックグラウンドサービス、自動化されたワークフローに最適です。
  • この方法では、カスタムOAuth アプリケーションと、安全に保管されたクライアント資格情報が必要です。
  • 重要： Power BI 管理者は、Power BI 管理ポータルのテナント設定 -> 開発者向け設定でサービスプリンシパル認証を有効にする必要があります。
    • これは、組織全体で有効にすることも、特定のセキュリティグループに制限することもできます（きめ細かな制御を行う場合に推奨）。
    • Entra アプリの登録には、追加のAPI 権限や OAuth スコープは必要ありません。アクセスは、Power BI 管理者の設定とワークスペースのロールの割り当てによって制御されます。
  • この方法を使用するためにカスタムOAuth アプリケーションを登録し、クライアント資格情報を構成するには、Entra ID でのサービスプリンシパルアプリの作成 を参照してください。
• AzureServicePrincipalCert – セキュアまたは規制された環境における証明書ベースの認証向け。
  • コンプライアンス要件が厳しいセキュリティ重視の環境での長時間実行されるジョブに最適です。
  • この方法では、カスタムOAuth アプリケーションと有効なクライアント証明書が必要です。
  • 重要： Power BI 管理者は、Power BI 管理ポータルのテナント設定 -> 開発者向け設定でサービスプリンシパル認証を有効にする必要があります。
    • これは、組織全体で有効にすることも、特定のセキュリティグループに制限することもできます（きめ細かな制御を行う場合に推奨）。
    • Entra アプリの登録には、追加のAPI 権限や OAuth スコープは必要ありません。アクセスは、Power BI 管理者の設定とワークスペースのロールの割り当てによって制御されます。
  • カスタムOAuth アプリケーションを登録してクライアント証明書をアップロードするには、Entra ID でのサービスプリンシパルアプリの作成 を参照してください。

Note： Power BI ワークスペースと登録されたサービスプリンシパルは、同じMicrosoft Entra テナントに属している必要があります。XMLA 接続は、クロステナントアクセスをサポートしていません。

ステップ2：必要な接続プロパティの設定

AuthScheme を設定した後、選択した認証方法に必要な接続プロパティを設定します。 これらのプロパティは、ドライバーが安全に認証を行い、Microsoft Entra ID（旧称：Azure Active Directory）からアクセストークンを取得できるようにします。 使用するOAuth アプリケーションが埋め込み型かカスタムか、またユーザー資格情報、クライアントシークレット、または証明書のいずれで認証するかによって、必要なプロパティの内容は異なります。

Note：AzureAD 認証の場合、組み込みOAuth アプリケーションは、必要なDelegated アクセス許可を自動的に要求します。 カスタムOAuth アプリケーションを登録する場合は、Microsoft Entra ID でDelegated アクセス許可Dataset.Read.All とWorkspace.Read.All を追加します。 サービスプリンシパル認証では、API のアクセス許可を追加する必要はありません。アクセスは、Power BI 管理者の設定とワークスペースのロールの割り当てによって完全に制御されます。

ステップ3：対象のPower BI ワークスペースの設定

認証の設定が完了したら、Workspace プロパティを設定して、接続したいMicrosoft Power BI ワークスペースを指定します。 Power BI Premium 容量でホストされているワークスペースのみがサポートされます。 ワークスペースがPremium 容量でない場合、接続は失敗します。

Power BI でワークスペースを開くことで、そのワークスペースの容量を確認できます。 ワークスペース名の横にあるダイヤモンドのアイコンを探してください。これは、そのワークスペースがPremium 容量に割り当てられていることを示しています。

詳細はPower BI ライセンスの種類 を参照してください。

重要：サービスプリンシパルは、XMLA エンドポイントにアクセスするために、対象ワークスペースで少なくともMember ロールを持っている必要があります。Admin アクセスはオプションであり、必須ではありません。

Entra ID（Azure AD）

Note：Microsoft はAzure AD をEntra ID にリブランドしました。ユーザーがEntra ID 管理サイトを操作する必要があるトピックでは、Microsoft が使用している名称と同じものを使用します。ただし、名前または値が"Azure AD" を参照しているCData 接続プロパティは、依然として存在します。

Microsoft Entra ID は、マルチテナント型のクラウドベースのID およびアクセス管理プラットフォームです。 OAuth ベースの認証フローに対応しており、ドライバーによるMicrosoft Power BI XMLA エンドポイントへのセキュアなアクセスを実現します。

Web アプリケーションを介したEntra ID への認証には、必ずはじめにカスタムOAuth アプリケーションを作成して登録する必要があります。 これにより、アプリケーションは独自のリダイレクトURI を定義し、クレデンシャルのスコープを管理し、組織固有のセキュリティポリシーに準拠することができるようになります。

カスタムOAuth アプリケーションの作成および登録方法の詳細については、Entra ID（Azure AD）アプリケーションの作成 を参照してください。

AuthScheme をAzureAD に設定した後の認証手順は、環境によって異なります。 デスクトップアプリケーション、Web ベースのワークフロー、またはヘッドレスシステムから接続する方法の詳細については、以下のセクションを参照してください。

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

デスクトップアプリケーションでは、ドライバーに組み込まれたOAuth アプリケーション、またはMicrosoft Entra ID に登録されたカスタムOAuth アプリケーションのいずれかを使用して認証を行うことができます。

オプション1：組み込みOAuth アプリケーションの使用

これはドライバーに含まれている、事前登録済みのアプリケーションです。 セットアップが簡単で、独自の認証情報を登録する必要がないため、開発環境、単一ユーザー向けツール、または迅速かつ簡単な認証が求められる構成に最適です。

次の接続プロパティを設定します。

• AuthScheme：AzureAD
• InitiateOAuth：
  • GETANDREFRESH – 初回ログイン時に使用します。ログインページを起動し、トークンを保存します。
  • REFRESH – すでに有効なアクセストークンおよびリフレッシュトークンを取得している場合は、この設定を使用します。保存されたトークンを再利用するため、ユーザーに再度プロンプトを表示することはありません。

接続時には、ドライバーは既定のブラウザでMicrosoft Entra のサインインページを開きます。 サインインしてアクセスを許可すると、ドライバーはアクセストークンおよびリフレッシュトークンを取得し、OAuthSettingsLocation で指定されたパスに保存します。

オプション2：カスタムOAuth アプリケーションの使用

組織でセキュリティポリシーの管理、リダイレクトURI の設定、アプリケーションのブランディングなど、より高度な制御が必要な場合は、代わりにMicrosoft Entra ID にカスタムOAuth アプリケーションを登録し、接続時にその値を指定することができます。

登録時に、以下の値を記録してください。

• OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
• OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
• CallbackURL：アプリケーション登録時に定義したリダイレクトURI。

カスタムOAuth アプリケーションの登録とリダイレクトURI の設定方法の詳細については、Entra ID（Azure AD）アプリケーションの作成 を参照してください。

次の接続プロパティを設定します。

• AuthScheme： AzureAD
• InitiateOAuth：
  • GETANDREFRESH – 初回ログイン時に使用します。ログインページを起動し、トークンを保存します。
  • REFRESH – すでに有効なアクセストークンおよびリフレッシュトークンを取得している場合は、この設定を使用します。保存されたトークンを再利用するため、ユーザーに再度プロンプトを表示することはありません。
• OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
• OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
• CallbackURL：アプリケーション登録時に定義したリダイレクトURI。

認証後、トークンはOAuthSettingsLocation に保存されます。 これらの値はセッションをまたいで保持され、アクセストークンの有効期限が切れた際に自動的に更新されるため、次回以降の接続時に再度ログインする必要はありません。

ヘッドレスマシン

CI / CD パイプライン、バックグラウンドサービス、サーバーベース連携などのヘッドレス環境では、対話型のブラウザが使用できません。 AzureAD を使用して認証するには、別のデバイス上のブラウザでOAuth フローを完了し、その認証結果をヘッドレスシステムに転送する必要があります。

セットアップオプション ：

• Verifier code を取得および交換
  • 別のデバイスを使用してサインインし、Verifier code を取得します。ヘッドレスシステムがこのコードを使用してトークンを要求します。
• OAuth 設定ファイルを転送
  • 別のデバイスで認証を行い、その後、保存されたトークンファイルをヘッドレス環境にコピーします。

Verifier code の使用

1. ブラウザを備えたデバイスで：
   • カスタムOAuth アプリケーションを使用する場合は、次のプロパティを設定します。
     • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
     • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
   • GetOAuthAuthorizationUrl ストアドプロシージャを呼び出し、サインインURL を生成します。
   • 返されたURL をブラウザで開きます。サインインして、ドライバーにアクセス許可を与えます。verifier code を含むコールバックURL にリダイレクトされます。
   • サインイン後、リダイレクトURL のcode パラメータの値を保存します。この値は後でOAuthVerifier 接続プロパティを設定する際に使用します。
2. ヘッドレスマシンで：
   • 次のプロパティを設定します。
     • AuthScheme：AzureAD
     • OAuthVerifier：保存したverifier code。
     • OAuthSettingsLocation：OAuth トークンの値を保存するファイルのパス。
     • カスタムアプリケーションの場合：
       • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
       • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
   • トークンを保存した後、以下の設定により再利用できます。
     • OAuthSettingsLocation：アクセストークンの自動リフレッシュを有効にするために、この場所がドライバーに読み書きのアクセス許可を与えることを確認してください。
     • カスタムアプリケーションの場合：
       • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
       • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。

OAuth 設定を転送

1. ブラウザを備えたデバイスで：
   • デスクトップアプリケーションセクションの説明に従って接続します。
   • 接続後、トークンはOAuthSettingsLocation のファイルパスに保存されます。デフォルトのファイル名はOAuthSettings.txt です。

   暗号化された値はシステムレジストリに保存されます。

2. ヘッドレスマシンで：
   • OAuth 設定ファイルをマシンにコピーします。
   • 次のプロパティを設定します。
     • AuthScheme：AzureAD
     • OAuthSettingsLocation：アクセストークンの自動リフレッシュを有効にするために、この場所がドライバーに読み書きのアクセス許可を与えることを確認してください。
     • カスタムアプリケーションの場合：
       • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
       • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。

セットアップ後、ドライバーは保存されたトークンを使用してアクセストークンを自動的に更新するため、ブラウザや手動でのログインは必要ありません。

Azure サービスプリンシパル

Note：Microsoft はAzure AD をEntra ID にリブランドしました。ユーザーがEntra ID 管理サイトを操作する必要があるトピックでは、Microsoft が使用している名称と同じものを使用します。ただし、名前または値が"Azure AD" を参照しているCData 接続プロパティは、依然として存在します。

サービスプリンシパルは、Microsoft Entra ID（Azure AD）アプリケーション内のセキュリティオブジェクトであり、そのアプリケーションが特定のテナント内で何を行えるかを定義します。 サービスプリンシパルはEntra 管理センターで作成でき、Azure ポータルからもアクセス可能です。 作成プロセスの過程で、サービスプリンシパルがクライアントシークレットまたは証明書のどちらを経由してEntra リソースにアクセスするかも指定します。

接続先のサービスによっては、テナント管理者がサービスプリンシパル認証を有効にするか、サービスプリンシパルを適切なロールまたはセキュリティグループに割り当てる必要があります。

サービスプリンシパルの権限は、特定のユーザーに紐づくのではなく、割り当てられたロールに基づきます。 これらのロールは、アプリケーションがアクセスできるリソースと、実行できる操作を決定します。

サービスプリンシパルを使用して認証する場合、Entra ID でのサービスプリンシパルアプリの作成 で説明するようにEntra テナントにアプリケーションを登録する必要があります。

このサブセクションでは、接続前に設定する必要があるプロパティについて説明します。 これらは、クライアントシークレットで認証するか、証明書で認証するかによって異なります。

クライアントシークレットによる認証

• AuthScheme：AzureServicePrincipal。
• AzureTenant：接続するAzure AD テナント。
• OAuthClientId：アプリケーション設定のクライアントID。
• OAuthClientSecret：アプリケーション設定のクライアントシークレット。
• InitiateOAuth：GETANDREFRESH。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。

証明書による認証

• AuthScheme：AzureServicePrincipalCert。
• AzureTenant：接続するAzure AD テナント。
• OAuthClientId：アプリケーション設定のクライアントId。
• OAuthJWTCert：JWT 証明書のストア。
• OAuthJWTCertType：JWT 証明書ストアの種類。
• InitiateOAuth：GETANDREFRESH。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。

接続のトラブルシューティング

よくあるエラーやセットアップの問題については、接続のトラブルシューティング を参照してください。

OAuth 値のリフレッシュ

本製品 は、ブラウザベースのOAuth 認証交換中に取得されたテンポラリーOAuth アクセストークンをリフレッシュできます。デフォルトでは、本製品 は暗号化されたトークンを、DSN に対応するodbc.ini ファイルに保存します。System DSN の場合、このodbc.ini ファイルへのアクセスを制限できます。

トークンの自動交換を有効にするには、本製品 にシステムodbc.ini への書き込みアクセス権を与えます。または、OAuthSettingsLocation 接続プロパティを、ドライバーが読み書きアクセス権を持つ別のファイルパスに設定することもできます。

    OAuthSettingsLocation=/tmp/oauthsettings.txt
    

OAuth 認証の依存関係のインストール

OAuth 認証標準は、認証するユーザーにWeb ブラウザを使用したMicrosoft Power BI XMLA との通信を要求します。最初のOAuth インタラクションがドライバーがインストールされている同じマシン上で行われる場合（例えばデスクトップアプリケーションの場合）、本製品 はデフォルトブラウザを立ち上げるxdg-open プログラムにアクセスする必要があります。

この依存関係を満たすには、パッケージマネージャーに対応するパッケージをインストールします。

Debian/Ubuntu Package	RHEL/Fedora Package	File
xdg-utils	xdg-utils	xdg-open

ドライバーエンコーディングの設定

ODBC ドライバーは、ODBC ドライバーマネージャーで使用するエンコーディングを指定する必要があります。デフォルトでは、Unix 用のCData ODBC ドライバーはunixODBC と互換性のあるUTF-16 を使用するように設定されていますが、他のドライバーマネージャーでは代替エンコーディングが必要な場合があります。

また、ANSI ODBC API を使用するアプリケーションからODBC ドライバーを使用している場合は、ANSI コードページを設定する必要があります。例えば、ANSI アプリケーションに日本語の文字をインポートするには、設定ファイル'/opt/cdata/cdata-odbc-driver-for-powerbixmla/lib/cdata.odbc.powerbixmla.ini' でコードページを指定できます。

[Driver]
AnsiCodePage = 932