接続の確立

JDBC データソースの作成

Java アプリケーションから接続するJDBC データソースを作成できます。CData JDBC Driver for Microsoft Dataverse に基づくJDBC データソースの作成は、3つの基本ステップで構成されます。

ドライバーのJAR ファイルをクラスパスに追加します。JAR ファイルはインストールディレクトリの［lib］サブフォルダ内にあります。.lic ファイルはJAR ファイルと同じフォルダ内に配置される必要があることに注意してください。
ドライバークラスを入力します。次に例を示します。
```
cdata.jdbc.cds.CDSDriver
```
JDBC URL を入力します。次に例を示します。
```
jdbc:cds:InitiateOAuth=GETANDREFRESH;OrganizationUrl=https://myaccount.crm.dynamics.com/;

or

jdbc:cdata:cds:InitiateOAuth=GETANDREFRESH;OrganizationUrl=https://myaccount.crm.dynamics.com/;
```
上記の2つ目の形式は、同じURL 形式を使用しているドライバー間でアプリケーションに競合がある場合は、CData ドライバーを使用していることを確認するために常に使用できます。URL は "jdbc:cds:" または"jdbc:cdata:cds:" のいずれかから始まり、任意の接続プロパティの名前と値のペアをセミコロン区切りで入力します。

スキーマ

Microsoft Dataverse は、System とEntities の2つのSchema プロパティ値をサポートしています。

System：Web API を使用してエンティティやテーブルを直接クエリします。
Entities：EntityDefinitions エンティティセットパスを使用して、EntityMetadata エンティティとテーブルに関するメタデータを取得します。これは通常、より分かりやすい名前を提供しますが、追加のメタデータリクエストが必要になります。

Microsoft Dataverse への接続

Microsoft Dataverse データソースを認証するには、まずOrganizationURL プロパティを接続先の組織のURL に設定します。

例：https://[organization].crm.dynamics.com.

Entra ID（Azure AD）

本製品は、Entra ID を使用したOAuth 2.0 によるMicrosoft Dataverse への認証をサポートします。 OAuth の実際の動作は、使用される認証フローを決定するAuthScheme 接続プロパティの値に依存します。

以下の表は、AuthScheme、OAuth グラントタイプ、および典型的なユースケースの関係を概説したものです。


AuthScheme	OAuth グラントタイプ	ユースケース
`AzureAD`	認可コード	ブラウザ操作によるユーザーのログイン（デスクトップ / Web）、またはヘッドレス環境で別デバイスを使用してログイン
`AzureServicePrincipal`	クライアントクレデンシャル	クライアントシークレットを使用したアプリケーション単体でのアクセス
`AzureServicePrincipalCert`	クライアントクレデンシャル	証明書ベースの認証を使用したアプリケーション単体でのアクセス
`AzureMSI`	マネージドID	Azure のマネージドID を使用するAzure ホストのアプリ / サービス

デスクトップアプリケーション向け認可コードフロー

このフローは、ブラウザを通じたユーザーログインが必要なシナリオ向けに設計されています。

CData は、認可コードグラントタイプを使用したOAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成については、Entra ID（Azure AD）アプリケーションの作成を参照してください。両者の違いは、カスタムアプリケーションでは構成時に追加で2つの接続プロパティを設定する必要があるという点だけです。

次の接続プロパティを設定して、接続してください。

InitiateOAuth：GETANDREFRESH に設定。このプロパティを使えば、繰り返しOAuth の交換を行ったり、手動でOAuthAccessToken を設定する必要はなくなります。
OAuthClientId：（カスタムアプリケーションのみ）アプリケーション設定のクライアントId に設定。
OAuthClientSecret：（カスタムアプリケーションのみ）アプリケーション設定のクライアントシークレットに設定。
CallbackURL：アプリケーション設定のリダイレクトURL に設定。

接続すると、本製品はデフォルトブラウザでOAuth 認可エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。本製品はこれでOAuth 交換を完了します。

コールバックURL からアクセストークンを取得し、リクエストの認証に使用します。
既存のトークンの期限が切れたときは、新しいアクセストークンを自動的に取得します。
トークンと関連するOAuth 値をOAuthSettingsLocation に保存し、セッションを超えて持続させます。

Web アプリケーション向け認可コードフロー

このフローは、ホスティングされたWeb アプリケーション内でユーザーがブラウザを通じて認証するシナリオ用に設計されています。

Microsoft Dataverse にカスタムOAuth アプリを登録する必要があります。Entra ID（Azure AD）アプリケーションの作成を参照してください。それから本製品を使用してOAuth トークンの値を取得および管理します。

OAuth アクセストークンの取得

認証方法に応じて以下のいずれかの接続プロパティグループを設定します。

クライアントシークレット
- OAuthClientId：アプリ設定のクライアントId に設定。
- OAuthClientSecret：アプリ設定のクライアントシークレットに設定。
証明書
- OAuthClientId：アプリ設定のクライアントId に設定。
- OAuthJWTCert：JWT 証明書ストアに設定。
- OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアの種類に設定。

続いて以下のストアドプロシージャを呼び出し、OAuth 交換を完了します。

GetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。CallbackURL インプットをアプリ設定で指定したリダイレクトURI に設定します。
返されたURL をブラウザで開きます。ログインして、アプリケーションを認可します。認可後、ブラウザはコールバックURL にリダイレクトします。
GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定し、Verifier インプットを、コールバックURL のクエリ文字列のcode パラメータの値に設定します。

OAuthAccessToken 接続プロパティをストアドプロシージャで返された値に設定し、Microsoft Dataverse に接続します。アクセストークンの期限が切れたときは、GetOAuthAccessToken を呼び出し、新しいアクセストークンを取得します。

ヘッドレスマシン向け認可コードフロー

ヘッドレスマシンとは、ブラウザインターフェースを持たないマシンです。OAuth ではブラウザでのユーザー操作が必要なため、ブラウザを持つ別のマシンで認証を実行する必要があります。認証完了後、クレデンシャルをヘッドレスマシンに転送します。

サポートされているオプションは2つあります。

別のデバイスで認証し、検証コードを手動でコピーする
別のマシンで認証を完了し、保存されたOAuth 設定ファイルを転送する

いずれかのオプションを完了した後、ヘッドレスマシンでアクセストークンを自動的にリフレッシュするように本製品を設定します。

オプション1：検証コードを取得および交換

ブラウザを備えた別のマシンを使用してOAuth 検証コードを生成します。

ブラウザを備えたデバイスで、次の方法のいずれか1つを設定してください。

組み込みOAuth アプリケーション：
本製品は自動的にOAuth 認可URL を生成し、デフォルトのブラウザで開きます。ブラウザウィンドウが表示されたら、Microsoft アカウントでサインインし、要求された権限を付与します。認証後、クエリ文字列に検証コードを含むコールバックURL にリダイレクトされます。 code パラメータの値をコピーしてください。これがOAuthVerifier 接続プロパティの検証コードになります。
カスタムOAuth アプリケーション： 以下の接続プロパティを手動で設定します。
- InitiateOAuth：OFF に設定。
- OAuthClientId：登録されたアプリケーションに割り当てられたクライアントID に設定。
- OAuthClientSecret：登録されたアプリケーションに割り当てられたクライアントシークレットに設定。
次に、適切なCallbackURL を指定してGetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。プロシージャが返したURL をブラウザで開き、ログインしてアプリケーションにアクセス許可を与えます。検証コードをクエリ文字列に含むコールバックURL にリダイレクトされます。 code パラメータの値をコピーしてください。これが検証コードになります。

次に：検証コードをトークンと交換

ヘッドレスマシンで、以下の接続プロパティを設定して検証コードをアクセストークンとリフレッシュトークンに交換します。

InitiateOAuth：REFRESH に設定。
OAuthVerifier：上記で取得したverifier code に設定。
OAuthClientId：（カスタムアプリケーションのみ）登録したクライアントID に設定。
OAuthClientSecret：（カスタムアプリケーションのみ）登録したクライアントシークレットに設定。
OAuthSettingsLocation：ドライバーがトークン値を保存するファイルパスに設定。

この交換が完了し設定ファイルが生成されたら、以下のように接続を再設定します。

InitiateOAuth：REFRESH に設定。
OAuthClientId：（カスタムアプリケーションのみ）登録したクライアントID に設定。
OAuthClientSecret：（カスタムアプリケーションのみ）登録したクライアントシークレットに設定。
OAuthSettingsLocation：保存された設定ファイルの場所に設定。トークンが自動的に更新されるよう、本製品が読み書き可能であることを確認してください。

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

この方法では、ブラウザが使用可能なマシンで完全なOAuth フローを完了し、その結果の設定ファイルをヘッドレスマシンに転送します。

ブラウザ対応マシンで、デスクトップアプリケーションの説明に従って接続を設定します。
認証後、本製品は暗号化されたトークン値をOAuthSettingsLocation で指定されたファイルに保存します。デフォルトのファイル名はOAuthSettings.txt です。
接続をテストしてファイルが期待通りに動作することを確認し、ファイルをヘッドレスマシンにコピーします。

ヘッドレスマシン上で、以下のように接続を設定します。

InitiateOAuth：REFRESH に設定。
OAuthClientId：（カスタムアプリケーションのみ）登録したクライアントID に設定。
OAuthClientSecret：（カスタムアプリケーションのみ）登録したクライアントシークレットに設定。
OAuthSettingsLocation：コピーされたOAuth 設定ファイルのパスに設定。ファイルが本製品に読み取り / 書き込み権限を付与していることを確認してください。

クライアントクレデンシャル

クライアントクレデンシャルは、直接ユーザー認証が行われないOAuth のフローを指します。代わりに、クレデンシャルはアプリケーション自体のためだけに作成されます。アプリケーションで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。そのため、認証フローが標準とは少し違ったものになります。

クライアントOAuth フロー

クライアントOAuth フローに関連するすべての権限には、管理者の同意が必要です。これは、CData JDBC Driver for Microsoft Dataverse が埋め込まれたアプリをクライアントOAuth フローでは使用できないことを意味します。クライアントクレデンシャルを使用するには、独自のOAuth アプリの作成が必要になります。詳しくは、Entra ID（Azure AD）アプリケーションの作成を参照してください。

portal.azure.com の［アプリの登録］で［API のアクセス許可］に移動し、Microsoft Graph アクセス許可を選択します。アクセス許可には、委任されたアクセス許可とアプリケーションの許可の2つの異なるアクセス許可セットがあります。クライアントクレデンシャル認証時に使用されるアクセス許可は、［アプリケーションの許可］の下にあります。インテグレーションに必要なアクセス許可を選択します。

認証タイプに応じて、以下のいずれかの接続プロパティグループを設定すると、接続できるようになります。

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

クライアントクレデンシャルでの認証は、他の接続同様に自動的に行われますが、ユーザーにプロンプトするウィンドウは表示されません。ユーザーコンテキストがないため、ブラウザのポップアップは必要ないからです。接続が行われ、内部的に処理されます。

Azure サービスプリンシパル

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

Azure サービスプリンシパルは、ロールに基づいたアプリケーションベースの認証です。これは、認証がユーザーごとではなく、アプリケーションごとに行われることを意味します。アプリケーションで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで、割り当てられたロールに基づいて実行されます。リソースへのアプリケーションのアクセスは、割り当てられたロールの権限によって制御されます。

Azure サービスプリンシパル認証の設定方法については、Entra ID（AzureAD）でのサービスプリンシパルアプリの作成を参照してください。

Managed Service Identity (MSI)

Azure VM 上でMicrosoft Dataverse を実行しており、マネージドID（MSI）認証情報を自動的に取得して接続したい場合は、AuthScheme を AzureMSI に設定します。

User-Managed Identities

マネージドID のトークンを取得するには、OAuthClientId プロパティを使用してマネージドID のclient_id を指定します。

VM に複数のユーザーが割り当てられたマネージドID がある場合は、OAuthClientId も指定する必要があります。