1. Oracle GoldenGate for Distributed Applications and Analytics
  2. データの複製
  3. ターゲット
  4. Microsoft Fabric OneLake

9.2.26 Microsoft Fabric OneLake

Microsoft Fabricは、統合されたソリューションを必要とする企業向けに設計された、エンドツーエンドの分析およびデータ・プラットフォームです。OneLakeは、Fabricプラットフォームに組み込まれており、ワークロードによってもたらされる組織的データすべてを格納する統合された場所を提供します。https://learn.microsoft.com/en-us/fabric/onelake/を参照してください。OneLakeイベント・ハンドラを使用して、操作レコードを含むファイルを次のターゲットにロードできます:
  • Microsoft Fabric内のレイクハウス
  • Microsoft Fabric内のミラー化データベース
この項の内容は次のとおりです。

親トピック: ターゲット

9.2.26.1 OneLakeイベント・ハンドラの前提条件

  • Azureクラウド・アカウントの設定。
  • Microsoft Fabricの設定。
    • Microsoft Fabricの容量とワークスペースが存在する必要があります。
    • Microsoft Fabricのレイクハウスまたはミラー化データベースが、レイクハウス・ターゲットまたはミラー化データベース・ターゲットそれぞれに対して存在する必要があります。
    • Microsoft FabricワークスペースにアクセスするためのMicrosoft Entra IDアプリを作成します。
    • アプリには、少なくともワークスペースに対するコントリビュータ・ロールが付与されている必要があります。
    • Fabric APIにアクセスするために、アプリの登録(サービス主体)を有効にします。
      • 「Admin Portal」->「Tenant Settings」->「Service principals can use Fabric APIs」->「Enabled for the entire organization」
    • OneLakeに格納されているデータへのリモート・アクセスを有効にします
      • 「Admin Portal」->「User can access data stored in OneLAke using Apps external to Fabric」。
  • Azure Storage File Data Lake用のJava Software Development Kit (SDK)

親トピック: Microsoft Fabric OneLake

9.2.26.2 Azure Data Lake Gen2へのOneLakeマッピング

  • ストレージ・アカウント: Azureストレージ・アカウントには、すべてのAzureストレージ・データ・オブジェクト(blob、ファイル共有、キュー、テーブル、ディスク)が含まれます。
    • OneLakeストレージ・アカウント名は常にonelakeです。
  • コンテナ: コンテナは、ファイル・システムのディレクトリと同様に、blobのセットを編成します。ストレージ・アカウントには制限のない数のコンテナを含めることができ、コンテナには制限のない数のblobを格納できます。
    • OneLakeコンテナ名は、OneLakeワークスペース名にマップされます。
  • エンドポイント: Azure Storageサービス・エンドポイント。

親トピック: Microsoft Fabric OneLake

9.2.26.3 OneLakeイベント・ハンドラの構成

親トピック: Microsoft Fabric OneLake

9.2.26.3.1 OneLakeイベント・ハンドラの自動構成

OneLakeレプリケーションでは、複数のコンポーネント(ファイル・ライター・ハンドラ、Avroフォーマッタ、Parquetイベント・ハンドラ、ORCイベント・ハンドラ、OneLakeイベント・ハンドラなど)を構成する必要があります。自動構成機能では、ユーザーによる構成が最小限になるように、これらのコンポーネントが自動構成されます。自動構成によって変更されたプロパティは、ハンドラのログ・ファイルに記録されます。

自動構成でレイクハウス・ターゲットにデータを複製できるようにするには、パラメータgg.target=fabric_lakehouseを設定します。

自動構成でミラー化データベース・ターゲットにデータを複製できるようにするには、パラメータgg.target=fabric_mirrored_databaseを設定します。

親トピック: OneLakeイベント・ハンドラの構成

9.2.26.3.2 ファイル・ライター・ハンドラの構成

ファイル・ライター・ハンドラ名は、gg.target構成に基づいて事前設定されます。たとえば、gg.target=fabric_lakehouseの場合、ファイル・ライター・ハンドラ名は値fabric_lakehouseに設定され、そのプロパティは、レイクハウスに必要な値に自動的に設定されます。この例の場合は、次のようにファイル・ライター・ハンドラのプロパティを追加または編集できます: gg.handler.fabric_lakehouse.inactivityRollInterval=1m

親トピック: OneLakeイベント・ハンドラの構成

9.2.26.3.3 Parquet/ORCイベント・ハンドラの自動構成

イベント・ハンドラ名は、ファイル形式の構成に基づいて、値parquetまたはorcに事前設定されます。

親トピック: OneLakeイベント・ハンドラの構成

9.2.26.3.3.1 OneLakeイベント・ハンドラでのParquet/ORCのファイル形式構成

  • Parquetファイルを必要とするユースケースの場合は(オープン・ミラーリングやvanilla Parquet形式など)、自動構成によってAvroフォーマッタが構成され、それがParquetイベント・ハンドラおよびOneLakeイベント・ハンドラと連結されます。
    これは、次のように構成されます: gg.format=parquet

    ノート:

    オープン・ミラーリング・ターゲット(gg.target=fabric_mirrored_database)の場合、ファイル形式の構成は固有であり、変更できません。
  • ORCファイルを必要とするユースケースの場合は、自動構成によってAvroフォーマッタが構成され、それがORCイベント・ハンドラおよびOneLakeイベント・ハンドラと連結されます。これは、次のように構成されます: gg.format=orc

9.2.26.3.4 OneLakeイベント・ハンドラの構成

OneLakeイベント・ハンドラ名は、値onelakeに事前設定されています。

gg.targetを、次の値のいずれかに設定する必要があります:

  • fabric_lakehouse: Microsoft Fabric内のレイクハウスに複製する場合。
  • fabric_mirrored_database: Microsoft Fabric内のミラー化データベースに複製する場合。
プロパティ 必須/オプション 有効な値 デフォルト 説明
gg.eventhandler.onelake.workspace 必須 文字列 なし Microsoft Fabricワークスペース名を設定します。
gg.eventhandler.onelake.lakehouse 必須 文字列 なし レイクハウス・ターゲットにのみ適用されます。Microsoft Fabricレイクハウス名を設定します。
gg.eventhandler.onelake.mirror 必須 文字列 なし ミラー化データベース・ターゲットにのみ適用されます。Fabric内のミラー化データベース名を設定します。
gg.eventhandler.onelake.tenantId オプション 文字列 なし アプリケーションのAzureテナントIDを設定します。
gg.eventhandler.onelake.clientId オプション 文字列 なし アプリケーションのAzureクライアントIDを設定します。
gg.eventhandler.onelake.clientSecret オプション 文字列 なし 認証のAzureクライアント・シークレットを設定します。
gg.eventhandler.onelake.pathMappingTemplate オプション OneLakeへのデータファイルのランディング・パスを動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。 gg.formatがfabric_mirrored_databaseに設定されている場合、デフォルト値は${catalogname}.MountedRelationalDatabase/Files/LandingZone/${schemaname}.schema/${tablename}です。これは変更できません。gg.target=fabric_lakehouseの場合、デフォルト値は${catalogname}.lakehouse/Files/ogg/${groupName}/${schemaname}.schema/${tablename}であり、これは変更できます。 定数と組み合せてキーワードを使用して、実行時にパス名を動的に生成します。パス名の例: ogg/data/${fullyQualifiedTableName}。サポートされているキーワードの詳細は、「テンプレートのキーワード」を参照してください。
gg.eventhandler.onelake.fileNameMappingTemplate オプション 実行時にデータファイル名を動的に生成するために使用される、解決可能なキーワードと定数を含む文字列。 gg.formatがfabric_mirrored_databaseに設定されている場合、この値は${custom[]}に設定されます。これは編集できません。gg.target=fabric_lakehouseの場合、デフォルト値はアップストリームのハンドラに基づき、これは変更できます。 定数と組み合せてキーワードを使用して、一意のファイル名を実行時に動的に生成します。通常、ファイル名は、${fullyQualifiedTableName}_${groupName}_${currentTimestamp}.txtという形式に従います。
gg.eventhandler.onelake.endpoint オプション 文字列 https://onelake.dfs.fabric.microsoft.com Fabric OneLakeエンドポイントを設定します。
gg.format オプション parquet、orc、またはGG for DAAプラガブル・フォーマッタ名のいずれか。 parquet レイクハウス・ターゲットにのみ適用されます。Fabric OneLakeファイル形式を設定します。詳細は、「レイクハウス・ターゲットの場合のファイル形式」を参照してください。

親トピック: OneLakeイベント・ハンドラの構成

9.2.26.3.5 レイクハウス・ターゲットの場合のファイル形式

パラメータgg.formatを構成してファイル形式を設定できます。

これは、次の値のいずれかに設定できます:

  • parquet: Parquet形式のファイルを生成します。
  • orc: ORC形式のファイルを生成します。
  • Oracle GoldenGate for Distributed Applications and Analytics (GG for DAA)でサポートされているその他のプラガブル形式。

親トピック: OneLakeイベント・ハンドラの構成

9.2.26.3.6 OneLakeイベント・ハンドラのクラスパス構成

クラスパスに次の依存性へのパスが含まれていることを確認します:

  • Hadoop依存性を含むParquetイベント・ハンドラ依存性。
  • Azure Storage File DataLake Java SDK。

親トピック: OneLakeイベント・ハンドラの構成

9.2.26.3.6.1 OneLakeイベント・ハンドラの依存性

依存性ダウンローダ・スクリプトonelake.shを使用すると、OneLake依存性をダウンロードできます。または、次のmaven座標を使用して、OneLake依存性を手動でダウンロードできます。 

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-storage-file-datalake</artifactId>
        <version>12.20.0</version>
    </dependency>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-identity</artifactId>
        <version>1.13.1</version>
    </dependency>
</dependencies>

gg.classpath構成パラメータを編集してAzure Storage File Data Lake SDKへのパスを含めます。

9.2.26.3.7 OneLakeイベント・ハンドラの認証

次の内容を構成することで、Azure Storageデバイスを認証できます:

  • tenantID
  • clientId
  • clientSecret

親トピック: OneLakeイベント・ハンドラの構成

9.2.26.3.7.1 AzureテナントID、クライアントIDおよびクライアント・シークレット

AzureテナントIDを取得するには:

  • Microsoft Azureポータルに移動します。
  • 左側のリストから「Azure Active Directory」を選択し、「Azure Active Directory」パネルを表示します。
  • 「Azure Active Directory」パネルで「プロパティ」を選択し、Azure Active Directoryのプロパティを表示します。

    AzureテナントIDは、「ディレクトリID」とマークされているフィールドです。

  • AzureクライアントIDおよびクライアント・シークレットを取得するには:
    • Microsoft Azureポータルに移動します。
    • 左側のリストから「すべてのサービス」を選択し、Azureサービスのリストを表示します。
    • フィルタ・コマンド・ボックスに「アプリ」と入力し、リストされたサービスから「アプリの登録」を選択します。
    • Microsoft Fabricワークスペースにアクセスするために作成した、アプリの登録を選択します。

      「アプリの登録」に表示されるアプリケーションIDは、クライアントIDです。クライアント・シークレットは、新しいキーが追加されたときに生成されるキー文字列です。

      この生成されたキー文字列は、キーの作成時に1回のみ表示されます。生成されたキー文字列がわからない場合は、別のキーを作成し、生成されたキー文字列を確実に取得してください。

9.2.26.3.8 OneLakeイベント・ハンドラのプロキシ構成

プロキシ・サーバーより後ろでプロセスを実行する場合は、プロパティjvm.bootoptionsを使用すると、既知のJavaプロキシ・プロパティを使用してプロキシ・サーバー構成を設定できます。たとえば: 
jvm.bootoptions=-Dhttps.proxyHost=some-proxy-address.com -Dhttps.proxyPort=80 -Djava.net.useSystemProxies=true

親トピック: OneLakeイベント・ハンドラの構成

9.2.26.3.9 レイクハウス・ターゲットの場合の構成例 

gg.target=fabric_lakehouse
#TODO: format can be 'parquet' or 'orc' or one of the pluggable formatter types. Default is 'parquet'.
#gg.format=parquet
#TODO: Edit the Fabric workspace name.
gg.eventhandler.onelake.workspace=<workspace-name>
#TODO: Edit the Fabric lakehouse name.
gg.eventhandler.onelake.lakehouse=<lakehouse-name>
#TODO: Edit the tenant ID of the application.
gg.eventhandler.onelake.tenantId=<azure-tenant-id>
#TODO: Edit the client ID of the application.
gg.eventhandler.onelake.clientId=<azure-client-id>
#TODO: Edit the client secret for the authentication.
gg.eventhandler.onelake.clientSecret=<azure-client-secret>
#TODO: Edit the classpath to include Hadoop, Parquet, and Azure DataLake SDK dependencies.
gg.classpath=$THIRD_PARTY_DIR/hadoop/*:$THIRD_PARTY_DIR/parquet/*:$THIRD_PARTY_DIR/onelake/*
#TODO: Edit the proxy configuration.
#jvm.bootoptions=-Dhttps.proxyHost=some-proxy-address.com -Dhttps.proxyPort=80 -Djava.net.useSystemProxies=true

親トピック: OneLakeイベント・ハンドラの構成

9.2.26.3.10 ミラー化データベース・ターゲットの場合の構成例 

gg.target=fabric_mirrored_database
#TODO: Edit the Fabric workspace name.
gg.eventhandler.onelake.workspace=<workspace-name>
#TODO: Edit the Fabric mirror Database name.
gg.eventhandler.onelake.mirror=<mirror-name>
#TODO: Edit the tenant ID of the application.
gg.eventhandler.onelake.tenantId=<azure-tenant-id>
#TODO: Edit the client ID of the application.
gg.eventhandler.onelake.clientId=<azure-client-id>
#TODO: Edit the client secret for the authentication.
gg.eventhandler.onelake.clientSecret=<azure-client-secret>
#TODO: Edit the classpath to include Hadoop, Parquet, and Azure DataLake SDK dependencies.
gg.classpath=$THIRD_PARTY_DIR/hadoop/*:$THIRD_PARTY_DIR/parquet/*:$THIRD_PARTY_DIR/onelake/*
#TODO: Edit the proxy configuration.
#jvm.bootoptions=-Dhttps.proxyHost=some-proxy-address.com -Dhttps.proxyPort=80 -Djava.net.useSystemProxies=true

親トピック: OneLakeイベント・ハンドラの構成

9.2.26.4 OneLakeイベント・ハンドラでの主キーの更新

主キーのUPDATEの動作は、ファイル形式の構成によって異なります。

親トピック: Microsoft Fabric OneLake

9.2.26.4.1 Microsoft Fabric内のミラー化データベース

ファイル形式がgg.format=fabric_mirroringに設定されている場合、主キーのUPDATE操作は、DELETE操作と、その後に続くINSERT操作に分割されます。この動作は変更できません。

親トピック: OneLakeイベント・ハンドラでの主キーの更新

9.2.26.4.2 Microsoft Fabric内のレイクハウス

gg.target=fabric_lakehouseが設定されている場合、デフォルトでは、主キーのUPDATE操作によってReplicatの異常終了が発生します。

この動作は、フォーマッタ・プロパティgg.handler.onelake.format.pkUpdateHandlingの構成によって変更できます。

プロパティgg.handler.onelake.format.pkUpdateHandlingには、次の入力のいずれかを指定できます。

  • abend: 主キーのUPDATEが処理されるとReplicatが異常終了します。
  • update: Replicatで、主キーのUPDATEは、通常のUPDATEとして処理されます。
  • delete-insert: Replicatにより、主キーのUPDATEは、DELETE操作と、その後に続くINSERT操作に分割されます。

親トピック: OneLakeイベント・ハンドラでの主キーの更新

9.2.26.5 OneLakeイベント・ハンドラに関するトラブルシューティングと診断

  • サポートされていない操作:
    • 表のDROP/RENAMEのDDL操作は、Replicatプロセスによって複製されません。
    • 表の列の名前変更は、Fabric Mirroring形式のファイルを使用するMicrosoftアプリケーションではサポートされていません。
    • TRUNCATE操作は複製できません。
  • エラー: 
    com.azure.identity.CredentialUnavailableException: EnvironmentCredential authentication unavailable.Environment variables are not fully configured.
    これは、Azure認証パラメータtenantId、clientIdおよびclientSecretが構成されていないことを示しています。認証パラメータを構成するには、「AzureテナントID、クライアントIDおよびクライアント・シークレット」を参照してください。
  • エラー: 
    java.lang.IllegalArgumentException: Invalid tenant id provided. You can locate your tenant id by following the instructions  listed here:
https://learn.microsoft.com/partner-center/find-ids-and-domain-names
    これは、認証パラメータtenandIdが無効であることを示しています。認証パラメータを構成するには、「AzureテナントID、クライアントIDおよびクライアント・シークレット」を参照してください。
  • エラー: 
    com.microsoft.aad.msal4j.MsalServiceException: AADSTS700016: Application with identifier '<invalid_clientId>' was  not found in the directory '<tenant
 name>'.
    これは、値が<invalid_client_id>である認証パラメータclientIdは正しくないことを示しています。認証パラメータを構成するには、「AzureテナントID、クライアントIDおよびクライアント・シークレット」を参照してください。
  • エラー: 
    com.microsoft.aad.msal4j.MsalServiceException: AADSTS7000215: Invalid client secret provided.
    これは、認証パラメータclientSecretが正しくないことを示しています。認証パラメータを構成するには、「AzureテナントID、クライアントIDおよびクライアント・シークレット」を参照してください。
  • エラー: 
    com.azure.storage.file.datalake.models.DataLakeStorageException:  Status code 404,
"{"error":{"code":"ArtifactNotFound","message":"Request Failed with  Artifact 'gglakehouse1_invalid.lakehouse' is not found in workspace
'ggworkspace1'."}}"
    これは、Fabricワークスペース名またはレイクハウス名が無効であることを示しています。そのFabricワークスペースまたはレイクハウスが存在しない場合は、Replicatプロセスを開始する前にこれらを作成する必要があります。構成パラメータgg.eventhandler.onelake.workspaceおよびgg.eventhandler.onelake.lakehouseが、それぞれそのFabricウェアハウス名およびレイクハウス名に設定されていることを確認してください。
  • エラー: 
    ONELAKE-00073 The event handler cannot proceed. The stage  file '<file_name>' in the directory '<directory_name>'  contains one or more truncate operations.
Truncate operations cannot be  replicated into Microsoft Fabric OneLake Generic Mirror. Modify the  GoldenGate replicat parameter file and remove the line that contains  GETTRUNCATES and
restart the replicat process.
    Replicatプロセスによって処理された1つ以上のTRUNCATE操作があります。続行するには、GETTRUNCATESパラメータをパラメータ・ファイルから削除し、Replicatプロセスを再起動する必要があります。
  • エラー: 
    ONELAKE-00082 File name sequence number for table QASOURCE.TCUSTMER has reached the maximum limit of 99,999,999,999,999,999,999.
    OneLake内のバックログをクリアするか、順序番号が最も大きい最後のファイルをパージし、Replicatプロセスを再起動する必要があります。
  • エラー: 
    The operation record in the trail sequence'<seqno>' at offset '<offset>' for the table '<table>' has missing column values.
    OneLakeレプリケーションには完全イメージが必要です。UPDATE操作用の完全イメージを含む証跡ファイルを再生成し、レプリケーション・プロセスを再起動する必要があります。
  • ミラー化データベース・ターゲット:
    • エラー: 
      ONELAKE-00073 The event handler cannot proceed. The stage file '<file_name>' in  the directory '<directory_name>' contains one or more truncate  operations. Truncate operations cannot bereplicated into Mirrored  Database in Microsoft Fabric. Modify the GoldenGate replicat
parameter  file and remove the line that contains GETTRUNCATES and restart the  replicat process.

      Replicatプロセスによって処理された1つ以上のTRUNCATE操作があります。

      続行するには、GETTRUNCATESパラメータをパラメータ・ファイルから削除し、Replicatプロセスを再起動する必要があります。

    • エラー: 
      ONELAKE-00082 File name sequence number for table QASOURCE.TCUSTMER has reached the maximum limit of
99,999,999,999,999,999,999.

      OneLake内のバックログをクリアするか、順序番号が最も大きい最後のファイルをパージし、Replicatプロセスを再起動する必要があります。

    • エラー: 
      The operation record in the trail sequence'<seqno>' at offset  '<offset>' for the table '<table>'
has missing column values

      Microsoft Fabric内のミラー化データベースへのレプリケーションには、完全イメージが必要です。

      UPDATE操作用の完全イメージを含む証跡ファイルを再生成し、レプリケーション・プロセスを再起動する必要があります。

親トピック: Microsoft Fabric OneLake