接続の確立

コネクタ内で利用可能なオブジェクトは、"cdata.lakebase" モジュールからアクセスできます。モジュールのオブジェクトを直接使用するには：

モジュールを以下のようにインポートします。
```
import cdata.lakebase as mod
```
接続を確立するには、以下のような適切な接続文字列を使用してコネクタオブジェクトからconnect() メソッドを呼び出します。
```
mod.connect("User=lakebase;Password=admin;Database=lakebase;Server=127.0.0.1;Port=5432")
```

Lakebase への接続

Lakebase に接続するには以下のプロパティを設定します。

DatabricksInstance：Databricks インスタンスまたはサーバーのホスト名。instance-abcdef12-3456-7890-abcd-abcdef123456.database.cloud.databricks.com の形式で指定します。
Server：Lakebase データベースをホスティングしているサーバーのホスト名またはIP アドレス。
Port（オプション）：Lakebase データベースをホスティングしているサーバーのポート。デフォルトは5432 に設定されています。
Database（オプション）：Lakebase サーバーへの認証後に接続するデータベース。デフォルトでは認証ユーザーのデフォルトデータベースに設定されています。

Lakebase の認証スキーム

Lakebase は、ワークスペースレベルのAPI を呼び出すため、次の2種類のOAuth ベースの認証スキームをサポートしています：OAuthClient およびOAuthPKCE。

OAuthClient

OAuthClient は、OAuth のクライアントクレデンシャルグラント種別を使用します。この認証スキームでは、OAuthClient 認証の設定に記載されているように、接続するためにサービスプリンシパルに対して追加の設定を実行する必要があります。

認証はOAuth クライアントクレデンシャルフローを介して処理されます。このフローには直接的なユーザー認証は含まれません。代わりに、アプリケーション自体にのみ適用される資格情報を使用します。 CData Python Connector for Lakebase は、サービスプリンシパル自体を使用して認証し、関連する権限はサービスプリンシパルで定義されます。

埋め込みのOAuth クレデンシャルは提供されないため、OAuthClient 認証スキームを指定するには、OAuthClient 認証の設定に記載されているように、サービスプリンシパルの追加設定を実行する必要があります。

以下の設定パラメータを設定します。

AuthScheme：OAuthClient。
OAuthClientId：サービスプリンシパルを設定したときに割り当てられたクライアントID（コンシューマーキーとも呼ばれます）。このID は、認証時にOAuth 認可サーバーにアプリケーションを識別させるために必要です。
OAuthClientSecret：サービスプリンシパルを設定したときに割り当てられたクライアントシークレット（アプリケーションシークレットまたはコンシューマーシークレットとも呼ばれます）。この機密情報は、OAuth 認可サーバーに対してアプリケーションを認証するために使用されます。

OAuthPKCE

OAuthPKCE は、PKCE（Proof Key for Code Exchange）を使用したOAuth code グラント種別を使用して、クロスサイトリクエストフォージェリおよび認可コードインジェクション攻撃から保護します。

この認証スキームでは、認証は、クライアントがアクセストークンと交換する一時的なコードの使用を介して処理されます。コード自体は認可サーバーから取得され、ユーザーはクライアントが要求している情報を確認し、リクエストを承認または拒否できます。

以下の設定パラメータを設定します。

AuthScheme：OAuthPKCE。
User：認証するユーザーのユーザーID。

Lakebase への認証

Lakebase に接続するために必要な接続パラメータと、選択した認証形式に必要な設定パラメータを設定したら、以下のセクションで説明されているようにLakebase に認証できます。

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

デスクトップアプリケーションからLakebase に初めて認証する場合、OAuth フローの過程でInitiateOAuth を2回設定する必要があります

初回ログイン時、InitiateOAuth をGETANDREFRESH に設定する必要があります。これによりログインページが起動し、トークンが保存されます。
有効なアクセストークンとリフレッシュトークンを取得したら、InitiateOAuth をREFRESH に再設定できます。これにより、ユーザーに再度プロンプトを表示することなく保存されたトークンが再利用されます。これは無人マシンで役立ちます。

認証後、トークンはOAuthSettingsLocation に保存されます。これらの値はセッション間で永続化され、アクセストークンの期限が切れたときに自動的に更新するために使用されます。これは、後続の接続時に再度ログインする必要がないことを意味します。

Web アプリケーション

Web アプリケーション経由で接続する場合、本製品を使用してOAuth トークンの値を取得および管理します。

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

上記のようにOAuthClientId およびOAuthClientSecret を設定したら、OAuthAccessToken を取得します。

Authscheme=OAuthClient の場合、InitiateOAuth をGETANDREFRESH に設定します。
Authscheme=OAuthPKCE のユーザー対話型フローの場合、OAuth 交換を完了するには、以下のようにストアドプロシージャを呼び出します。
1. GetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。CallbackURL インプットをアプリケーション設定で指定したコールバックURL に設定します。
  ストアドプロシージャがOAuth エンドポイントのURL を返します。
2. URL を開き、ログインして、アプリケーションを認可します。コールバックURL にリダイレクトされます。
3. GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。Verifier インプットを、コールバックURL のクエリ文字列の"code" パラメータに設定します。

アクセストークンとリフレッシュトークンを取得すると、データに接続し、OAuth アクセストークンを自動または手動でリフレッシュすることができるようになります。

OAuth アクセストークンの自動リフレッシュ：

ドライバーがOAuth アクセストークンを自動的にリフレッシュするようにするには、Lakebase に初めて認証するときに次の接続パラメータを設定します。

InitiateOAuth：REFRESH。
OAuthAccessToken：GetOAuthAccessToken によって返されたアクセストークン。
OAuthRefreshToken：GetOAuthAccessToken によって返されたリフレッシュトークン。
OAuthSettingsLocation：本製品がOAuth トークン値を保存する場所。これは接続間で維持されます。

以降のすべてのデータ接続では、OAuthAccessToken およびOAuthRefreshToken の値は、OAuthSettingsLocation から取得されます。

OAuth アクセストークンの手動リフレッシュ：

データ接続時に手動でOAuth アクセストークンをリフレッシュするために必要な値は、OAuth リフレッシュトークンのみです。

まず、RefreshOAuthAccessToken ストアドプロシージャを使用して手動でOAuthAccessToken をリフレッシュします。

次に、RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを指定します。新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定し、新しい接続をオープンします。

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

ヘッドレスマシン

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

Note： 以下の手順は、OAuthPKCE 認証スキームでの使用を目的としています。OAuthClient 認証スキームはブラウザの対話を必要としないため、ヘッドレスマシンでもInitiateOAuth=GETANDREFRESH を使用できます。

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

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

Verifier code の使用

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

OAuth 設定を転送

ブラウザを備えたデバイスで、デスクトップアプリケーションセクションの説明に従って接続します。接続後、トークンはOAuthSettingsLocation のファイルパスに保存されます。デフォルトのファイル名はOAuthSettings.txt です。
ヘッドレスマシンで：
1. OAuth 設定ファイルをマシンにコピーします。
2. 次のプロパティを設定します。
  - InitiateOAuth：REFRESH
  - OAuthSettingsLocation：アクセストークンの自動リフレッシュを有効にするために、この場所がドライバーに読み書きのアクセス許可を与えることを確認してください。

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