DataWorks:セルフホスト型サービスに基づくエクステンションの開発とデプロイ

前提条件

メッセージサブスクリプションを有効化する必要があります。セルフホスト型サービスを使用したエクステンションのデプロイは、EventBridge のメッセージ配信機能に依存します。DataWorks のオープンイベントメッセージが EventBridge のイベントバスに送信されるように設定されていることを確認する必要があります。また、このイベントバスからのメッセージが、オンプレミスまたはクラウドにデプロイされたサービスプログラムにルーティングされることも確認する必要があります。

制限事項

• DataWorks Enterprise Edition のユーザーのみがエクステンションモジュールを使用できます。

• エクステンションモジュールは、中国 (北京)、中国 (杭州)、中国 (上海)、中国 (張家口)、中国 (深セン)、中国 (成都)、米国 (シリコンバレー)、米国 (バージニア)、ドイツ (フランクフルト)、日本 (東京)、中国 (香港)、およびシンガポールのリージョンで利用できます。

注意事項

• 開発者バックエンドに対する読み取りおよび書き込み権限を持つのは、Open Platform 管理者、テナント管理者、Alibaba Cloud アカウント、および AliyunDataWorksFullAccess ポリシーがアタッチされた RAM ユーザーのみです。権限管理の詳細については、「グローバルモジュールの権限制御」および「RAM ポリシーによるプロダクトレベルおよびコンソールアクセスの管理」をご参照ください。

• バージョン制限：DataWorks Enterprise Edition のサブスクリプションが有効期限切れになると、すべてのエクステンションが無効になり、イベントチェックをトリガーできなくなります。トリガーされたが最終状態に達していないチェックは、自動的にパスします。

• ノード制限：機械学習 (PAI) ノード、do-while ノード、for-each ノードなど、内部ノードを含む複合ノードに対してチェックがトリガーされた場合、後続の操作に進む前にすべての内部ノードがチェックにパスする必要があります。

• トリガーの説明：複数のエクステンションを同じエクステンションポイントイベントに関連付けることができます。これは、単一のイベントが複数のエクステンションをトリガーできることを意味します。

ステップ 1：エクステンションの依存関係の設定

エクステンションを開発する際、以下の依存関係を pom.xml ファイルに追加します。EventBridge は、イベントを処理および消費するためにさまざまなタイプのエンドポイントをサポートしています。以下の依存関係に加えて、EventBridge で設定されたイベントターゲットと最終的なメッセージルーティングに基づいて、他の依存関係を設定できます。

<dependency>
 <groupId>com.aliyun</groupId>
 <artifactId>dataworks_public20200518</artifactId>
 <version>5.6.0</version>
</dependency>

<build>
        <plugins>
              <plugin>
                  <groupId>org.apache.maven.plugins</groupId>
                  <artifactId>maven-shade-plugin</artifactId>
                  <version>3.2.1</version>
                  <executions>
                    <execution>
                      <phase>package</phase>
                      <goals>
                        <goal>shade</goal>
                      </goals>
                      <configuration>
                        <filters>
                          <filter>
                            <artifact>*:*</artifact>
                            <excludes>
                              <exclude>META-INF/*.SF</exclude>
                              <exclude>META-INF/*.DSA</exclude>
                              <exclude>META-INF/*.RSA</exclude>
                            </excludes>
                          </filter>
                        </filters>
                      </configuration>
                    </execution>
                  </executions>
              </plugin>
        </plugins>
</build>

ステップ 2：エクステンションコードの開発

EventBridge のイベントバスによってルーティングされたメッセージは、オンプレミスまたはクラウドにデプロイされたサービスにプッシュされます。このサービスは、イベントバスによってプッシュされた DataWorks メッセージを受信し、特定の DataWorks API を使用して処理結果とともにコールバックを送信します。

1. プログラムコードを開発します。

   メッセージ内容の解析

   DataWorks からプッシュされるイベントメッセージのフォーマットについては、「付録：DataWorks から EventBridge に送信されるメッセージのフォーマット」をご参照ください。メッセージフォーマットでは、data に特定のメッセージ内容が含まれます。開発中、data.eventCode フィールドを使用してメッセージタイプを識別し、id フィールドを使用してメッセージの詳細を取得できます。

   説明

   OpenEvent は EventBridge を使用して DataWorks のイベントメッセージを配信します。エクステンションを開発する前に、EventBridge で DataWorks のメッセージをサブスクライブする必要があります。詳細については、「メッセージサブスクリプションの有効化」をご参照ください。

   処理ロジックの記述

   必要に応じて、イベントバスによってプッシュされたメッセージを処理します。エクステンション開発中に、以下のメソッドを使用して開発効率とアプリケーションのパフォーマンスを向上させることができます。

   • extension.project.disabled などの高度な機能：エクステンションパラメーターの設定を使用して、特定のワークスペースでエクステンションを無効にします。

   • Data Studio モジュールに関連するエクステンションポイントを処理する際、GetIDEEventDetail API を呼び出して、MessageId に基づいてエクステンションポイントイベントがトリガーされた時点のデータスナップショットを取得できます。

   説明

   MessageId は、メッセージ内の id フィールドに対応します。詳細については、「付録：DataWorks から EventBridge に送信されるメッセージのフォーマット」をご参照ください。

   処理結果を DataWorks に返す

   エクステンションサービスは、OpenAPI を介してエクステンションポイントの処理結果を DataWorks に返す必要があります。コールバックを行う際は、エクステンションポイントイベントが発生したモジュールに基づいて、適切な OpenAPI を選択する必要があります。

   • DataStudio のエクステンションポイントイベント：UpdateIDEEventResult API を使用して、処理結果を含むコールバックを送信します。

   • オペレーションセンターのエクステンションポイントイベント：UpdateWorkbenchEventResult API を使用して、処理結果を含むコールバックを送信します。

   • その他のモジュールのエクステンションポイントイベント：CallbackExtension API を使用して、処理結果を含むコールバックを送信します。

   コールバック API は、現在のサービスのエクステンション (ExtensionCode)、イベントメッセージ (MessageId)、およびメッセージ処理結果 (CheckResult) を返します。

   • CheckResult の値：

     • OK：エクステンションはこのエクステンションポイントイベントのチェックにパスしました。

     • FAIL：エクステンションはこのエクステンションポイントイベントのチェックに失敗しました。後続のプログラム実行への影響を防ぐために、エラーを速やかに確認し、対処する必要があります。

     • WARN：エクステンションはこのエクステンションポイントイベントのチェックにパスしましたが、警告があります。

   • ExtensionCode：このコードは、後述のセクションで説明するようにエクステンションを登録した後、DataWorks のエクステンションリストページから取得できます。

   • MessageId：メッセージ内の ID フィールドに対応します。詳細については、「DataWorks から EventBridge に送信されるメッセージのフォーマット」をご参照ください。

2. コードの開発が完了したら、プログラムを実行可能な .jar ファイルにパッケージ化して、後続のサービスデプロイに備えます。

ステップ 3：エクステンションのデプロイ

エクステンションコードを開発およびデバッグした後、パッケージ化されたコードを Alibaba Cloud Elastic Compute Service (ECS) または他のサービスプロバイダー上のアプリケーションサービスとしてデプロイできます。

ステップ 1：エクステンションの登録

エクステンションを開発して使用する前に、DataWorks に登録して、後続の開発に対応する Extension Code を取得する必要があります。以下にエクステンションを登録する手順を説明します。

1. 開発者バックエンドタブに移動します。

   DataWorks コンソールにログインします。上部のナビゲーションバーで、目的のリージョンを選択します。左側のナビゲーションウィンドウで、その他 > オープンプラットフォームを選択します。表示されたページで、オープンプラットフォームへ移動をクリックします。開発者バックエンドタブが表示されます。

2. エクステンションを登録します。

   1. 左側のナビゲーションウィンドウで、エクステンションをクリックしてエクステンションページを開きます。

   2. エクステンションリスト > エクステンションの登録をクリックします。セルフホスト型サービスでデプロイを選択し、エクステンションの詳細を設定します。

      パラメーターの説明

      パラメーター	設定方法
      エクステンション名	エクステンションのカスタム名で、識別のために使用されます。
      処理するエクステンションポイント	このエクステンションが処理するエクステンションイベントメッセージのタイプを選択します。サポートされているエクステンションポイントのリストについては、「サポートされているエクステンションポイントイベントのリスト」をご参照ください。必要に応じてエクステンションポイントを選択します。 説明 選択後、インターフェイスは自動的にイベントと適用モジュールを一致させます。手動での設定は不要です。 エクステンションポイントイベントの制限：エクステンションポイントイベントは、テナントレベルとワークスペースレベルに分かれています。エクステンションを登録する際、1つのレベルのエクステンションポイントイベントしか選択できません。DataWorks でサポートされている各エクステンションポイントイベントのレベルについては、「開発リファレンス：イベントリストとメッセージフォーマット」をご参照ください。 Function Compute を使用してデプロイされたエクステンションは、現在データダウンロード前イベントのみをサポートしています。
      オーナー	エクステンションのオーナーです。これにより、ユーザーが問題に遭遇した場合にオーナーに連絡できます。
      テストワークスペース	エクステンションをテストするためのワークスペースを選択します。エクステンションは公開されずにテストワークスペースで有効になります。 エクステンションが公開される前に、開発者はテストワークスペースでエンドツーエンドのテストと検証を実行できます。イベントをトリガーすることで、DataWorks が EventBridge を介してメッセージを送信するか、エクステンションがメッセージを受信、レビュー、およびコールバックを送信するかをテストできます。 説明 処理するエクステンションポイントでテナントレベルのエクステンションポイントイベントを選択した場合、テストワークスペースを設定する必要はありません。
      エクステンション詳細 URL	エクステンションに関する詳細を提供するページの URL を入力します。これにより、ユーザーがエクステンションをよりよく理解し、使用するのに役立ちます。 エクステンションの詳細ページを開発し、その URL をここで設定できます。これにより、エクステンションがトリガーされたときに、ユーザーはチェックパスやブロック理由などの完全な検証プロセスを表示できます。
      エクステンションドキュメント URL	エクステンションのヘルプドキュメントの URL を入力します。 エクステンションのヘルプドキュメントページを開発し、その URL をここで設定できます。これにより、ユーザーはエクステンションの検証ロジックとプロパティについて学ぶことができます。
      エクステンションパラメーター設定	DataWorks は、開発中にパラメーターを使用して効率を向上させることをサポートしています。エクステンションコードで使用する必要があるパラメーターをここに追加します。 DataWorks が提供する一般的なシナリオ用の組み込みパラメーターを使用することも、独自に定義することもできます。 key=value 形式で、1行に1つずつ複数のパラメーターを追加できます。 説明 たとえば、組み込みパラメーター extension.project.disabled を使用して、特定のワークスペースでエクステンションを無効にすることができます。パラメーターの使用に関する詳細については、「高度な機能：エクステンションパラメーターの設定」をご参照ください。
      エクステンションオプション設定	エクステンションユーザー向けの設定項目を入力します。これにより、異なるワークスペースでエクステンションをパーソナライズして制御できます。エクステンション開発者は、ここでオプションを JSON 文字列として定義する必要があります。 たとえば、オプション設定を使用して、ユーザーが SQL の長さを自分で制御できるようにすることができます。JSON フォーマットについては、「高度な機能：エクステンションオプション設定の構成」をご参照ください。

3. エクステンションの登録を完了します。

   OK をクリックして完了します。

   説明

   登録が成功すると、エクステンションリストでエクステンションを表示できます。

ステップ 2：エクステンションの公開

エクステンションが開発、デプロイ、および DataWorks に登録された後、テスト、承認、および公開プロセスを完了する必要があります。その後、エクステンションのオーナー以外の管理者は、管理センターでエクステンションを有効にできます。詳細については、「エクステンションの適用」をご参照ください。

{
    "datacontenttype": "application/json;charset=utf-8", // data パラメーターのコンテンツのフォーマット。datacontenttype は application/json フォーマットのみをサポートします。
    "aliyunaccountid": "1111",// Alibaba Cloud アカウントの ID。
    "aliyunpublishtime": "2024-07-10T07:25:34.915Z",// EventBridge がイベントを受信した時刻。
    "data": {
              
             "tenantId": 28378****10656,// テナント ID。各 Alibaba Cloud アカウントは DataWorks のテナントに対応し、各テナントには独自の ID があります。この値は、DataWorks Data Studio の右上隅にあるユーザー情報セクションで確認できます。
             "eventCode": "xxxx"// イベントコード。
            
    },
    "aliyunoriginalaccountid": "11111",
    "specversion": "1.0",
    "aliyuneventbusname": "default",// DataWorks イベントメッセージを受信するために使用される EventBridge イベントバスの名前。
    "id": "45ef4dewdwe1-7c35-447a-bd93-fab****",// イベント ID。イベントを一意に識別する値。
    "source": "acs.dataworks",// イベントソース。イベントを提供するサービスです。これは、メッセージが DataWorks によってプッシュされたことを示します。
    "time": "2024-07-10T15:25:34.897Z",// イベントが発生した時刻。
    "aliyunregionid": "cn-shanghai",// イベントが受信されたリージョン。
    "type": "dataworks:ResourcesUpload:UploadDataToTable"// イベントタイプ。このイベントタイプを EventBridge コンソールで使用して、DataWorks によってプッシュされたすべてのメッセージをフィルタリングできます。Type の値はイベントごとに異なります。
}