LoginSignup
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 3 years have passed since last update.

@sugimount(sugi mount)

[Oracle Cloud] Data Integration で OCI CLI を使って、Parameter 付きタスクを実行してみた

Posted at

はじめに

前回の記事では、Data Integration に Parameter を設定して、入力ファイル名と出力ディレクトリを柔軟にする方法を紹介しました。今回の記事では、OCI CLI で Parameter 付き Task を実行する方法を紹介します。

Object Storage にデータ加工したいファイルを置いたときに、自動的に Data Integration の Task を実行したいユースケースがあると思います。この手順が参考になると思います。Parameter をどのように OCI CLI で実行すれば分からなかったので、検証した内容を紹介します。

Task Run Parameter 無し

まず最初に、Parameter が無い Task をシンプルに実行する方法を紹介します。次のコマンドで実行できます。

oci data-integration task-run create \
--workspace-id ocid1.disworkspace.oc1.ap-tokyo-1.amaaaaaassl65iqa4726obzimlzokp4p2tscrb3ykye2xin4ltwdnf5ioh4q \
--application-key 2848c0c8-8400-4ac2-8d75-bcf38ad7c9b2 \
--registry-metadata '
{"aggregatorKey" : "ee07f136-f827-4b78-bcca-c8b10a952527"}
' \
--key "f87dec30-59fc-4a88-b2a1-0f003ec8ea30" \
--debug

実行例

> oci data-integration task-run create \
  --workspace-id ocid1.disworkspace.oc1.ap-tokyo-1.amaaaaaassl65iqa4726obzimlzokp4p2tscrb3ykye2xin4ltwdnf5ioh4q \
  --application-key 2848c0c8-8400-4ac2-8d75-bcf38ad7c9b2 \
  --registry-metadata '
  {"aggregatorKey" : "ee07f136-f827-4b78-bcca-c8b10a952527"}
  ' \
  --key "f87dec30-59fc-4a88-b2a1-0f003ec8ea30"

{
  "data": {
    "bytes-processed": 0,
    "config-provider": null,
    "description": null,
    "end-time-millis": 0,
    "error-message": null,
    "identifier": "FIXINTEGRATIONTASK_1600548955209",
    "key": "f87dec30-59fc-4a88-b2a1-0f003ec8ea30",
    "key-map": {},
    "last-updated": 0,
    "metadata": {
      "aggregator-key": "ee07f136-f827-4b78-bcca-c8b10a952527",
      "created-by": "ocid1.user.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "created-by-name": "oracleidentitycloudservice/xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "identifier-path": null,
      "info-fields": null,
      "labels": null,
      "registry-version": 1,
      "time-created": "2020-09-19T20:55:55.521000+00:00",
      "time-updated": "2020-09-19T20:55:55.521000+00:00",
      "updated-by": "ocid1.user.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "updated-by-name": "oracleidentitycloudservice/xxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "model-type": "TASK_RUN",
    "model-version": "20190408",
    "name": "FixIntegrationTask_1600548955209",
    "object-status": 8,
    "object-version": 1,
    "opc-request-id": "A245DF515E334288BE3F7BA83707000C/4D58487A0080AE4A81DFF669F3573B2F",
    "parent-ref": {
      "parent": null
    },
    "records-written": 0,
    "start-time-millis": 1600548955209,
    "status": "NOT_STARTED",
    "task-type": "INTEGRATION_TASK"
  }
}

パラメータ説明

  • --workspace-id : Task を作成した Workspace の OCID を指定

次のコマンドで表示できます

> oci data-integration workspace list
{
  "data": [
    {
      "compartment-id": "ocid1.compartment.oc1..aaaaaaaaxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "description": null,
      "display-name": "privateworkspace01",
      "freeform-tags": {},
      "id": "ocid1.disworkspace.oc1.ap-tokyo-1.amaaaaaassl65iqa4726obzimlzokp4p2tscrb3ykye2xin4ltwdnf5ioh4q", <================= これを指定
      "lifecycle-state": "ACTIVE",
      "state-message": "Container Creation Succeeded",
      "time-created": "2020-09-13T22:59:21.438000+00:00",
      "time-updated": "2020-09-19T07:00:00+00:00"
    }
  ]
}
  • --application-key : Task を Public した Application の Key を指定

次のコマンドで表示できます

> oci data-integration application list --workspace-id ocid1.disworkspace.oc1.ap-tokyo-1.aaaaaaaaxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{
  "data": {
    "items": [
      {
        "application-version": 2,
        "dependent-object-metadata": [
          {
            "action": null,
            "identifier": "SUGITESTFLOW",
            "key": "dff20820-2652-4f7c-979e-8329596fc84f",
            "name": "sugitestflow",
            "name-path": "/sugiproject/sugitestflow",
            "object-version": 4,
            "type": "UNKNOWN_ENUM_VALUE"
          },
          {
            "action": null,
            "identifier": "SUGIPROJECT",
            "key": "854d3da6-245f-4666-859c-0e524d195a39",
            "name": "sugiproject",
            "name-path": null,
            "object-version": 1,
            "type": "UNKNOWN_ENUM_VALUE"
          }
        ],
        "description": null,
        "identifier": "SUGIAPPLICATION",
        "key": "2848c0c8-8400-4ac2-8d75-bcf38ad7c9b2", <================= これを指定
        "key-map": null,
        "metadata": {
          "aggregator-key": "1d1ee8f5-b5b4-46de-aae6-22ed1ec34f8c",
          "identifier-path": null,
          "info-fields": null,
          "labels": null,
          "registry-version": 1,
          "time-created": "2020-09-19T07:29:07.469000+00:00",
          "time-updated": "2020-09-19T07:29:28.975000+00:00",
          "updated-by": "User",
          "updated-by-name": "Unknown"
        },
        "model-type": "INTEGRATION_APPLICATION",
        "model-version": "20200310",
        "name": "sugiapplication",
        "object-status": 8,
        "object-version": 4,
        "parent-ref": {
          "parent": null
        },
        "published-object-metadata": {
          "30930087-a582-45d2-980d-7fec296d2773": {
            "action": "CREATED",
            "identifier": "PARAMETERTESTINTEGRATIONTASK",
            "key": "30930087-a582-45d2-980d-7fec296d2773",
            "name": "ParameterTestIntegrationTask",
            "name-path": "/sugiproject/ParameterTestIntegrationTask",
            "object-version": 1,
            "type": "INTEGRATION_TASK"
          }
        }
      },
      {
        "application-version": 1,
        "dependent-object-metadata": [],
        "description": null,
        "identifier": "DEFAULT_APPLICATION",
        "key": "086c9114-648c-4bb7-8ce7-212952d479d0",
        "key-map": null,
        "metadata": {
          "aggregator-key": "1d1ee8f5-b5b4-46de-aae6-22ed1ec34f8c",
          "created-by": "DIAgent::ABE4E1666",
          "created-by-name": "DIAgent::ABE4E1666",
          "identifier-path": null,
          "info-fields": null,
          "labels": null,
          "registry-version": 1,
          "time-created": "2020-09-13T23:06:27.356000+00:00",
          "time-updated": "2020-09-13T23:06:27.356000+00:00",
          "updated-by": "DIAgent::ABE4E1666",
          "updated-by-name": "DIAgent::ABE4E1666"
        },
        "model-type": "INTEGRATION_APPLICATION",
        "model-version": "20200310",
        "name": "Default Application",
        "object-status": 10,
        "object-version": 1,
        "parent-ref": {
          "parent": null
        },
        "published-object-metadata": {}
      }
    ]
  },
  "opc-total-items": "2"
}
  • --registry-metadata : {"aggregatorKey" : "<Your Task Key>"} の書式で、Application に Publish した Task Key を指定

Data Integration のこの画面からコピー可能

1600547462115.png

  • --key : Task Run Key の指定。任意の一意な文字列を指定可能。UUID でもいいし、どのような文字列でも問題ない(と思う)。一意にするために、実行時刻の Unix TIme などを指定すると良さそう

実行完了後、Copy Task Run Key を押すとコピー出来る文字列を、実行側で指定可能

1600549176990.png

Task Run Parameter 有り

では、本題です。Parameter 有りで、実行する方法を紹介します。

cd ~/workdir/dataintegration_cli
oci data-integration task-run create \
--workspace-id ocid1.disworkspace.oc1.ap-tokyo-1.amaaaaaassl65iqa4726obzimlzokp4p2tscrb3ykye2xin4ltwdnf5ioh4q \
--application-key 2848c0c8-8400-4ac2-8d75-bcf38ad7c9b2 \
--registry-metadata '
{"aggregatorKey" : "f00c0f5c-da6d-4756-9fad-05b30840b181"}
' \
--key "f87dec30-59fc-4a88-b2a1-0f003ec8ea31" \
--config-provider file://configParameter.json \
--debug

パラメータの説明。説明済みのものは省略します。

  • --config-provider : Parameter として、上書きする各種情報を JSON データで指定

JSON ファイルの中身

> cat ~/workdir/dataintegration_cli/configParameter.json
{
    "bindings": {
        "INPUT_OBJECT_NAME": {
            "rootObjectValue": {
                "dataFormat": {
                    "formatAttribute": {
                        "delimiter": ",",
                        "encoding": "UTF-8",
                        "escapeCharacter": "\\",
                        "hasHeader": "true",
                        "modelType": "CSV_FORMAT",
                        "quoteCharacter": "\"",
                        "timestampFormat": "yyyy-MM-dd HH:mm:ss.SSS"
                    },
                    "type": "CSV"
                },
                "entity": {
                    "key": "dataref:4081caef-488a-440b-9d76-871912c4d3f0/input/FILE_ENTITY:paramtest02.csv",
                    "modelType": "FILE_ENTITY",
                    "name": "paramtest02.csv",
                    "resourceName": "FILE_ENTITY:paramtest02.csv"
                },
                "modelType": "ENRICHED_ENTITY"
            }
        }
    }
}

各種設定値で分かっていることを紹介します。Document に明確に書かれているわけではなく、検証で観察した挙動と推察で書いています。

{
    "bindings": { <=================== 固定文字列
        "INPUT_OBJECT_NAME": { <=================== Parameterを Assing した時に指定した Name を指定
            "rootObjectValue": { <=================== 固定文字列
                "dataFormat": { <=================== 固定文字列
                    "formatAttribute": { <=================== 固定文字列
                        "delimiter": ",", <=================== 固定文字列
                        "encoding": "UTF-8", <=================== 固定文字列
                        "escapeCharacter": "\\", <=================== 固定文字列
                        "hasHeader": "true", <=================== 固定文字列
                        "modelType": "CSV_FORMAT", <=================== 固定文字列
                        "quoteCharacter": "\"", <=================== 固定文字列
                        "timestampFormat": "yyyy-MM-dd HH:mm:ss.SSS" <=================== 固定文字列
                    },
                    "type": "CSV" <=================== 固定文字列
                },
                "entity": { <=================== 固定文字列
                    "key": "dataref:4081caef-488a-440b-9d76-871912c4d3f0/input/FILE_ENTITY:paramtest02.csv", <=================== 「4081caef-488a-440b-9d76-871912c4d3f0」は、Data Asset で定義した、Default Connection の ID。「paramtest02.csv」の部分は読み込ませたいファイル名を指定
                    "modelType": "FILE_ENTITY", <=================== 固定文字列
                    "name": "paramtest02.csv", <=================== 「paramtest02.csv」の部分は読み込ませたいファイル名を指定
                    "resourceName": "FILE_ENTITY:paramtest02.csv" <=================== 「paramtest02.csv」の部分は読み込ませたいファイル名を指定
                },
                "modelType": "ENRICHED_ENTITY" <=================== 固定文字列
            }
        }
    }
}

Input として指定する、paramtest02.csv は、このように格納されています。

1600552298823.png

中身はこんな感じです

name,id,userrank
satou,4,bronze
kimura,5,gold
takahashi,6,silver

OCI CLI を実行した結果です。このように正常に実行されます。

1600550075714.png

どうやって パラメータ を調べたの？

Config Provider などの各種パラメータで指定する文字列を把握するのに、色々ハマりました。備忘録として調べた方法を残しておきます。この調べた方法を参考にしてくれると嬉しいです。

まず、OCI CLI で Task Run を実行するためのコマンドを見つけます。Data Integration に関するコマンドを掘っていくと、それらしい名前のコマンドがわかります

oci data-integration task-run create

このコマンドの Option を調べるために、-h を指定してヘルプを出します。

oci data-integration task-run create -h

必須パラメータが上の方に書いているので、2つのパラメータが必須なことが分かります

REQUIRED PARAMETERS
       --application-key [text]

       DIS application key

       --workspace-id [text]

       DIS workspace id-

Optional Parameter の欄を見てみます。が、いったい何をどう指定すればいいのか、何もわかりません。

OPTIONAL PARAMETERS
       --config-provider [complex type]

       This is a complex type whose value must be valid JSON. The value can be
       provided  as  a string on the command line or passed in as a file using
       the file://path/to/file syntax.

       The --generate-param-json-input option  can  be  used  to  generate  an
       example  of  the JSON which must be provided. We recommend storing this
       example in a file, modifying it as needed and then passing it  back  in
       via the file:// syntax.

       --description [text]

       Detailed description for the object.

       --from-json [text]

       Provide  input to this command as a JSON document from a file using the
       file://path-to/file syntax.

       The --generate-full-command-json-input option can be used to generate a
       sample json file to be used with this command option. The key names are
       pre-populated  and  match  the  command  option  names  (converted   to
       camelCase  format,  e.g.  compartment-id  --> compartmentId), while the
       values of the keys need to be populated by the user  before  using  the
       sample  file  as  an input to this command. For any command option that
       accepts multiple values, the value of the key can be a JSON array.

       Options can still be provided on the command line. If an option  exists
       in  both  the  JSON document and the command line then the command line
       specified value will be used.

       For examples on usage of this option, please see our  "using  CLI  with
       advanced                JSON               options"               link:
       https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#AdvancedJSONOptions

       --identifier [text]

       Value  can  only contain upper case letters, underscore and numbers. It
       should begin with upper case letter or underscore.  The  value  can  be
       edited by the user.

       --key [text]

       The key of the object.

       --model-type [text]

       The type of the object.

       --model-version [text]

       The model version of an object.

       --name [text]

       Free  form  text  without any restriction on permitted characters. Name
       can have letters, numbers, and special characters.  The  value  can  be
       edited by the user and it is restricted to 1000 characters

       --registry-metadata [complex type]

       This is a complex type whose value must be valid JSON. The value can be
       provided as a string on the command line or passed in as a  file  using
       the file://path/to/file syntax.

       The  --generate-param-json-input  option  can  be  used  to generate an
       example of the JSON which must be provided. We recommend  storing  this
       example  in  a file, modifying it as needed and then passing it back in
       via the file:// syntax.

Document を見ようということで、Parameter に関するページ を見ましたが、GUI を使った設定しか書かれていません。では、次に、OCI CLI の Data Integration のページ を見てみましたが、これもよくわかりません。じゃあ次に、REST API のページ を見てみましたが、これもさっぱりよくわかりません。

このあたりのハードルでは、まだまだあきらめてはいけません。

Data Integration の Product Manager が書いている Blog を見てみます。Introduction to CLI, API for Oracle Cloud Infrastructure (OCI) Data Integration のページを発見しました。何かのヒントがありそうな気がします。画像が小さくわからないですが、拡大してみるとこんな感じのヒントがありました。・・・なるほど、これは、Parameter 無しで Task Runするときに渡すパラメータですね。registryMetadata と key に関するヒントが初めて手に入りました。これで、Parameter 無しで実行する方法が分かりました。

1600550887043.png

Product Manager の Blog でも、Parameter 付きで実行する方法が紹介されていませんでした。ならば仕方ないと、最終手段として、Chrome の Developer Tools を使って、解析を試みます。OCI Console で Task Run を実行する直前の画面に行き、Developer Tools を開き、Run を押します。

1600551660145.png

すると、taskRuns に関する通信ログが確認できました。このあたりが怪しそうですね。キャプチャしたデータを一旦 Export で、HAR ファイルで保存しておきます。

1600551723835.png

1個目の TaskRuns を見てみると、Request URL, Request Method, Status Code など、いかにも Task Run を Create してそうな内容となっていました。これは怪しそうだぞと思い、深掘りしていこうと思います。

1600551831026.png

Request の詳細の部分は、Request Payload で格納することが多いです。なので、下の方へスクロールしてみると、まさに configProvider の情報がありました。あと、key と registryMetadata も見つけました。PM Blog で書かれていた内容となっています。

1600551987562.png

configProvider を展開してみました。ずいぶんたくさん情報があるな、とは思いました。が、一旦この情報全て指定して実行してみると、正常に実行できました。このように、Document に書かれていない情報でも、Blog 情報や、Developer Tools で解析すれば情報を引き出せることがわかりました。

1600552083927.png

付録1 : Parameter 有 で実行 (他のファイル)

Input Bucket に、新たな paramtest03.csv を格納しました。

ファイルの中身はこんな感じです

name,id,userrank
yamashita,7,bronze
namazu,8,silver
murakami,9,gold

JSON のパラメータを作ります

変更前

{
    "bindings": {
        "INPUT_OBJECT_NAME": {
            "rootObjectValue": {
                "dataFormat": {
                    "formatAttribute": {
                        "delimiter": ",",
                        "encoding": "UTF-8",
                        "escapeCharacter": "\\",
                        "hasHeader": "true",
                        "modelType": "CSV_FORMAT",
                        "quoteCharacter": "\"",
                        "timestampFormat": "yyyy-MM-dd HH:mm:ss.SSS"
                    },
                    "type": "CSV"
                },
                "entity": {
                    "key": "dataref:4081caef-488a-440b-9d76-871912c4d3f0/input/FILE_ENTITY:paramtest02.csv",
                    "modelType": "FILE_ENTITY",
                    "name": "paramtest02.csv",
                    "resourceName": "FILE_ENTITY:paramtest02.csv"
                },
                "modelType": "ENRICHED_ENTITY"
            }
        }
    }
}

変更後

{
    "bindings": {
        "INPUT_OBJECT_NAME": {
            "rootObjectValue": {
                "dataFormat": {
                    "formatAttribute": {
                        "delimiter": ",",
                        "encoding": "UTF-8",
                        "escapeCharacter": "\\",
                        "hasHeader": "true",
                        "modelType": "CSV_FORMAT",
                        "quoteCharacter": "\"",
                        "timestampFormat": "yyyy-MM-dd HH:mm:ss.SSS"
                    },
                    "type": "CSV"
                },
                "entity": {
                    "key": "dataref:4081caef-488a-440b-9d76-871912c4d3f0/input/FILE_ENTITY:paramtest03.csv",
                    "modelType": "FILE_ENTITY",
                    "name": "paramtest03.csv",
                    "resourceName": "FILE_ENTITY:paramtest03.csv"
                },
                "modelType": "ENRICHED_ENTITY"
            }
        }
    }
}

OCI CLI で実行
--key　は毎回変更するようにしましょう。既に実行したことのある Key を指定するとエラーになります。

cd ~/workdir/dataintegration_cli
oci data-integration task-run create \
--workspace-id ocid1.disworkspace.oc1.ap-tokyo-1.amaaaaaassl65iqa4726obzimlzokp4p2tscrb3ykye2xin4ltwdnf5ioh4q \
--application-key 2848c0c8-8400-4ac2-8d75-bcf38ad7c9b2 \
--registry-metadata '
{"aggregatorKey" : "f00c0f5c-da6d-4756-9fad-05b30840b181"}
' \
--key "f87dec30-59fc-4a88-b2a1-0f003ec8ea32" \
--config-provider file://configParameter.json \
--debug

正常に実行できます

1600552753522.png

Output されたファイルです。namazu のデータが、silver なので、正しくフィルターされています。

name,id,userrank
namazu,8,silver

付録2 : Config Provider をすこしスリム化

Oracle で働いている方の Blog に次の記事があります。

Executing Tasks using Python SDK in Oracle Cloud Infrastructure Data Integration
https://medium.com/@dave.allan.us/executing-tasks-using-python-sdk-in-oracle-cloud-infrastructure-data-integration-tasks-bb3c10550395

この中に、Config Provider の Sample が書かれており、entity の下のファイル名の指定が若干スリムになっています。

1600552943547.png

これを参考にスリム化してみましょう

変更前

{
    "bindings": {
        "INPUT_OBJECT_NAME": {
            "rootObjectValue": {
                "dataFormat": {
                    "formatAttribute": {
                        "delimiter": ",",
                        "encoding": "UTF-8",
                        "escapeCharacter": "\\",
                        "hasHeader": "true",
                        "modelType": "CSV_FORMAT",
                        "quoteCharacter": "\"",
                        "timestampFormat": "yyyy-MM-dd HH:mm:ss.SSS"
                    },
                    "type": "CSV"
                },
                "entity": {
                    "key": "dataref:4081caef-488a-440b-9d76-871912c4d3f0/input/FILE_ENTITY:paramtest03.csv",
                    "modelType": "FILE_ENTITY",
                    "name": "paramtest03.csv",
                    "resourceName": "FILE_ENTITY:paramtest03.csv"
                },
                "modelType": "ENRICHED_ENTITY"
            }
        }
    }
}

変更後

{
    "bindings": {
        "INPUT_OBJECT_NAME": {
            "rootObjectValue": {
                "dataFormat": {
                    "formatAttribute": {
                        "delimiter": ",",
                        "encoding": "UTF-8",
                        "escapeCharacter": "\\",
                        "hasHeader": "true",
                        "modelType": "CSV_FORMAT",
                        "quoteCharacter": "\"",
                        "timestampFormat": "yyyy-MM-dd HH:mm:ss.SSS"
                    },
                    "type": "CSV"
                },
                "entity": {
                    "key": "dataref:4081caef-488a-440b-9d76-871912c4d3f0/input/FILE_ENTITY:paramtest03.csv",
                    "modelType": "FILE_ENTITY",
                    "objectStatus": 1
                },
                "modelType": "ENRICHED_ENTITY"
            }
        }
    }
}

OCI CLI で実行
--key　は毎回変更するようにしましょう。既に実行したことのある Key を指定するとエラーになります。

cd ~/workdir/dataintegration_cli
oci data-integration task-run create \
--workspace-id ocid1.disworkspace.oc1.ap-tokyo-1.amaaaaaassl65iqa4726obzimlzokp4p2tscrb3ykye2xin4ltwdnf5ioh4q \
--application-key 2848c0c8-8400-4ac2-8d75-bcf38ad7c9b2 \
--registry-metadata '
{"aggregatorKey" : "f00c0f5c-da6d-4756-9fad-05b30840b181"}
' \
--key "f87dec30-59fc-4a88-b2a1-0f003ec8ea34" \
--config-provider file://configParameter.json \
--debug

正常に実行出来ています。

1600553181077.png

実際の中身

name,id,userrank
namazu,8,silver

参考URL

Integration Tasks の紹介
https://blogs.oracle.com/dataintegration/integration-tasks-in-oracle-cloud-infrastructure-oci-data-integration

PM Blogs
https://blogs.oracle.com/dataintegration/oracle-cloud-infrastructure-data-integration

Blogs
https://medium.com/@dave.allan.us

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?