Workspace Model Registry Webhook

備考

プレビュー

Webhook を使用すると、Workspace Model Registry イベントをリッスンして、インテグレーションでアクションを自動的にトリガーできます。 Webhook を使用して、機械学習パイプラインを自動化し、既存の CI/CD ツールやワークフローと統合できます。たとえば、新しいモデルバージョンが作成されたときにCIビルドをトリガーしたり、本番運用へのモデル移行がリクエストされるたびにSlackを通じてチームメンバーに通知したりできます。

Webhook は、Databricks REST API または PyPI の Python クライアント databricks-registry-webhooks を通じて使用できます。

注記

Webhook は、Unity Catalog でモデルを使用する場合は使用できません。別の方法については、「ステージの移行リクエストを使用したり、イベントで Webhook をトリガーしたりできますか?」を参照してください。プライベートエンドポイント(パブリックインターネットからアクセスできないエンドポイント)へのWebhookの送信はサポートされていません。

Webhook イベント

これらのイベントの 1 つ以上でトリガーする Webhook を指定できます。

MODEL_VERSION_CREATED : 関連付けられたモデルに対して新しいモデルバージョンが作成されました。
MODEL_VERSION_TRANSITIONED_STAGE :モデル版のステージを変更しました。
TRANSITION_REQUEST_CREATED : ユーザーからモデルバージョンのステージの移行をリクエストされました。
COMMENT_CREATED : ユーザーが登録済みモデルにコメントを書き込んだ。
REGISTERED_MODEL_CREATED : 新しい登録済みモデルが作成されました。このイベントの種類は、レジストリ全体の Webhook に対してのみ指定でき、作成要求でモデル名を指定しないことで作成できます。
MODEL_VERSION_TAG_SET : ユーザーがモデルバージョンにタグを設定しました。
MODEL_VERSION_TRANSITIONED_TO_STAGING : モデルバージョンがステージングに移行されました。
MODEL_VERSION_TRANSITIONED_TO_PRODUCTION :モデル版を本番運用に移行しました。
MODEL_VERSION_TRANSITIONED_TO_ARCHIVED : モデル版をアーカイブしました。
TRANSITION_REQUEST_TO_STAGING_CREATED : ユーザーがモデルバージョンをステージングに移行するように要求しました。
TRANSITION_REQUEST_TO_PRODUCTION_CREATED :ユーザーからモデル版の本番運用への移行を要望されました。
TRANSITION_REQUEST_TO_ARCHIVED_CREATED : ユーザーがモデルバージョンのアーカイブを要求しました。

Webhook の種類

トリガーターゲットによって、Webhookには2種類あります。

HTTP エンドポイントを持つウェブフック (HTTP レジストリウェブフック): HTTP エンドポイント にトリガーを送信します。
ジョブトリガーを含む Webhook (ジョブレジストリ Webhook): Databricks ワークスペースでジョブをトリガーします。ジョブのワークスペースで IP 許可リストが有効になっている場合は、モデルレジストリのワークスペース IP を許可リストに登録する必要があります。詳細については、「ジョブレジストリ Webhook の IP 許可リスト」を参照してください。

また、Webhookには、その範囲に応じて、アクセス制御の要件が異なる、2種類あります。

モデル固有の Webhook : Webhook は、特定の登録済みモデルに適用されます。モデル固有の Webhook を作成、変更、削除、またはテストするには、登録済みモデルに対する CAN MANAGE 権限が必要です。
レジストリ全体の Webhook : Webhook は、新しい登録済みモデルの作成など、ワークスペース内の登録済みモデルのイベントによってトリガーされます。レジストリ全体の Webhook を作成するには、作成時に model_name フィールドを省略します。レジストリ全体の Webhook を作成、変更、削除、またはテストするには、ワークスペース管理者のアクセス許可が必要です。

ウェブフックペイロード

各イベントトリガーには、Webhook エンドポイントへの送信要求のペイロードに含まれる最小限のフィールドがあります。

アーティファクトパスの場所などの機密性の高い情報は除外されます。適切な ACL を持つユーザーとプリンシパルは、クライアントまたは REST APIs を使用して、この情報の Model Registry にクエリを実行できます。
ペイロードは暗号化されません。がDatabricks Webhook のソースであることを検証する方法については、セキュリティに関する情報を参照してください。
text フィールドはSlackとの統合を容易にします。 Slackメッセージを送信するには、WebフックURLとしてSlackウェブフックエンドポイントを指定してください。

ジョブレジストリ Webhook ペイロード

ジョブレジストリ Webhook のペイロードは、ジョブの種類によって異なり、ターゲットワークスペースの jobs/run-now エンドポイントに送信されます。

シングルタスクジョブ

単一タスクジョブには、タスクタイプに基づく 3 つのペイロードのいずれかがあります。

ノートブック and Python wheel ジョブ

ノートブック wheel ジョブと Python wheel ジョブには、フィールド event_messageを含むパラメーターディクショナリを含む JSON ペイロードがあります。

JSON
{
  "job_id": 1234567890,
  "notebook_params": {
    "event_message": "<Webhook Payload>"
  }
}

Python、JAR、Spark Submit ジョブ

Python、JAR、および Spark の送信ジョブには、パラメーターリストを含む JSON ペイロードがあります。

JSON
{
  "job_id": 1234567890,
  "python_params": ["<Webhook Payload>"]
}

その他すべてのジョブ

他のすべてのタイプのジョブには、パラメーターのない JSON ペイロードがあります。

JSON
{
  "job_id": 1234567890
}

マルチタスクジョブ

マルチタスクジョブには、さまざまなタスクの種類のすべてのパラメーターがアカウントに設定された JSON ペイロードがあります。

JSON
{
  "job_id": 1234567890,
  "notebook_params": {
    "event_message": "<Webhook Payload>"
  },
  "python_named_params": {
    "event_message": "<Webhook Payload>"
  },
  "jar_params": ["<Webhook Payload>"],
  "python_params": ["<Webhook Payload>"],
  "spark_submit_params": ["<Webhook Payload>"]
}

ペイロードの例

出来事： `MODEL_VERSION_TRANSITIONED_STAGE`

レスポンス

POST
/your/endpoint/for/event/model-versions/stage-transition
--data {
  "event": "MODEL_VERSION_TRANSITIONED_STAGE",
  "webhook_id": "c5596721253c4b429368cf6f4341b88a",
  "event_timestamp": 1589859029343,
  "model_name": "Airline_Delay_SparkML",
  "version": "8",
  "to_stage": "Production",
  "from_stage": "None",
  "text": "Registered model 'someModel' version 8 transitioned from None to Production."
}

出来事： `MODEL_VERSION_TAG_SET`

レスポンス

POST
/your/endpoint/for/event/model-versions/tag-set
--data {
  "event": "MODEL_VERSION_TAG_SET",
  "webhook_id": "8d7fc634e624474f9bbfde960fdf354c",
  "event_timestamp": 1589859029343,
  "model_name": "Airline_Delay_SparkML",
  "version": "8",
  "tags": [{"key":"key1","value":"value1"},{"key":"key2","value":"value2"}],
  "text": "example@yourdomain.com set version tag(s) 'key1' => 'value1', 'key2' => 'value2' for registered model 'someModel' version 8."
}

出来事： `COMMENT_CREATED`

レスポンス

POST
/your/endpoint/for/event/comments/create
--data {
  "event": "COMMENT_CREATED",
  "webhook_id": "8d7fc634e624474f9bbfde960fdf354c",
  "event_timestamp": 1589859029343,
  "model_name": "Airline_Delay_SparkML",
  "version": "8",
  "comment": "Raw text content of the comment",
  "text": "A user commented on registered model 'someModel' version 8."
}

安全

セキュリティのために、 Databricks には、ペイロードのヘッダーコンピュートに X-Databricks-Signature が含まれ、 SHA-256 アルゴリズムの HMAC を使用して Webhook に関連付けられた共有シークレットキーが含まれています。

さらに、Webhook の HttpUrlSpec に標準の Authorization ヘッダーを指定することで、送信要求に標準の Authorization ヘッダーを含めることができます。

クライアントの検証

共有シークレットが設定されている場合、ペイロードの受信者は、共有シークレットを使用してペイロードを HMAC エンコードし、エンコードされた値とヘッダーの X-Databricks-Signature を比較することで、HTTP 要求のソースを確認する必要があります。これは、SSL 証明書の検証が無効になっている場合 (つまり、 enable_ssl_verification フィールドが falseに設定されている場合) に特に重要です。

注記

enable_ssl_verification はデフォルトで true です。自己署名証明書の場合、このフィールドは falseにする必要があり、宛先サーバーは証明書の検証を無効にする必要があります。

セキュリティ上の理由から、Databricks では、ペイロードの HMAC エンコード部分を使用してシークレット検証を実行することをお勧めします。ホスト名の検証を無効にすると、要求が意図しないホストに悪意を持ってルーティングされるリスクが高まります。

Python
import hmac
import hashlib
import json

secret = shared_secret.encode('utf-8')
signature_key = 'X-Databricks-Signature'

def validate_signature(request):
  if not request.headers.has_key(signature_key):
    raise Exception('No X-Signature. Webhook not be trusted.')

  x_sig = request.headers.get(signature_key)
  body = request.body.encode('utf-8')
  h = hmac.new(secret, body, hashlib.sha256)
  computed_sig = h.hexdigest()

  if not hmac.compare_digest(computed_sig, x_sig.encode()):
    raise Exception('X-Signature mismatch. Webhook not be trusted.')

HTTP レジストリ Webhook の認証ヘッダー

Authorization ヘッダーが設定されている場合、クライアントは Authorization ヘッダーのベアラートークンまたは認証資格情報を確認して、HTTP 要求のソースを確認する必要があります。

ジョブレジストリ Webhook の IP 許可リスト

IP 許可リストが有効になっている別のワークスペースでジョブ実行をトリガーする Webhook を使用するには、Webhook が配置されているリージョンの NAT IP を許可リストに登録して、受信要求を受け入れる必要があります。

Webhook とジョブが同じワークスペースにある場合は、許可リストに IP を追加する必要はありません。

アカウントチームに連絡して、許可リストに登録する必要があるIPを特定します。

監査ログ

ワークスペースで監査ログが有効になっている場合、監査ログには次のイベントが含まれます。

Webhook の作成
Webhook の更新
Webhook を一覧表示する
ウェブフックを削除してください
Webhook のテスト
Webhook トリガー

Webhook トリガー監査ログ

HTTP エンドポイントを持つ Webhook の場合、Webhook に指定された URL に送信された HTTP 要求は、URL と enable_ssl_verification の値と共にログに記録されます。

ジョブトリガーを含む Webhook の場合、 job_id と workspace_url の値がログに記録されます。

例

このセクションには以下の内容が含まれます。

HTTP レジストリ Webhook ワークフローの例。
ジョブレジストリ Webhook ワークフローの例。
Webhook の例を一覧表示します。
2 つのサンプルノートブック: 1 つは REST API を示し、もう 1 つは Python クライアントを示しています。

HTTP レジストリ Webhook ワークフローの例

1. Webhook を作成する

HTTPS エンドポイントが Webhook イベント要求を受信する準備ができたら、Webhook Databricks REST API を使用して Webhook を作成できます。たとえば、Webhook の URL は、チャンネルにメッセージを投稿するために Slack を指すことができます。

Bash
$ curl -X POST -H "Authorization: Bearer <access-token>" -d \
'{"model_name": "<model-name>",
  "events": ["MODEL_VERSION_CREATED"],
  "description": "Slack notifications",
  "status": "TEST_MODE",
  "http_url_spec": {
    "url": "https://hooks.slack.com/services/...",
    "secret": "anyRandomString"
    "authorization": "Bearer AbcdEfg1294"}}' https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/create

Python
from databricks_registry_webhooks import RegistryWebhooksClient, HttpUrlSpec

http_url_spec = HttpUrlSpec(
  url="https://hooks.slack.com/services/...",
  secret="secret_string",
  authorization="Bearer AbcdEfg1294"
)
http_webhook = RegistryWebhooksClient().create_webhook(
  model_name="<model-name>",
  events=["MODEL_VERSION_CREATED"],
  http_url_spec=http_url_spec,
  description="Slack notifications",
  status="TEST_MODE"
)

レスポンス

{"webhook": {
   "id":"1234567890",
   "creation_timestamp":1571440826026,
   "last_updated_timestamp":1582768296651,
   "status":"TEST_MODE",
   "events":["MODEL_VERSION_CREATED"],
   "http_url_spec": {
     "url": "https://hooks.slack.com/services/...",
     "enable_ssl_verification": True
}}}

Databricks Terraform プロバイダーと databricks_mlflow_webhook を使用して HTTP レジストリ Webhook を作成することもできます。

2. Webhook をテストする

以前の Webhook は TEST_MODEで作成されたため、モックイベントをトリガーして、指定した URL にリクエストを送信できます。ただし、Webhook は実際のイベントではトリガーされません。テストエンドポイントは、指定された URL から受信した状態コードと本文を返します。

Bash
$ curl -X POST -H "Authorization: Bearer <access-token>" -d \
'{"id": "1234567890"}' \
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/test

Python
from databricks_registry_webhooks import RegistryWebhooksClient

http_webhook = RegistryWebhooksClient().test_webhook(
  id="1234567890"
)

レスポンス

{
 "status":200,
 "body":"OK"
}

3. Webhook をアクティブステータスに更新します

実際のイベントに対して Webhook を有効にするには、update 呼び出しを使用してそのステータスを ACTIVE に設定し、これを使用して他のプロパティを変更することもできます。

Bash
$ curl -X PATCH -H "Authorization: Bearer <access-token>" -d \
'{"id": "1234567890", "status": "ACTIVE"}' \
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/update

Python
from databricks_registry_webhooks import RegistryWebhooksClient

http_webhook = RegistryWebhooksClient().update_webhook(
  id="1234567890",
  status="ACTIVE"
)

レスポンス

{"webhook": {
   "id":"1234567890",
   "creation_timestamp":1571440826026,
   "last_updated_timestamp":1582768296651,
   "status": "ACTIVE",
   "events":["MODEL_VERSION_CREATED"],
   "http_url_spec": {
     "url": "https://hooks.slack.com/services/...",
     "enable_ssl_verification": True
}}}

4. Webhook を削除する

Webhook を無効にするには、そのステータスを DISABLED に設定するか (上記と同様の更新コマンドを使用)、削除します。

Bash
$ curl -X DELETE -H "Authorization: Bearer <access-token>" -d \
'{"id": "1234567890"}' \
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/delete

Python
from databricks_registry_webhooks import RegistryWebhooksClient

http_webhook = RegistryWebhooksClient().delete_webhook(
  id="1234567890"
)

レスポンス

{}

ジョブレジストリ Webhook ワークフローの例

ジョブレジストリ Webhook を管理するためのワークフローは HTTP レジストリ Webhook と似ていますが、唯一の違いは http_url_spec フィールドを置き換える job_spec フィールドです。

Webhook を使用すると、同じワークスペースまたは異なるワークスペースでジョブをトリガーできます。ワークスペースは、省略可能なパラメーター workspace_urlを使用して指定します。 workspace_urlが存在しない場合、デフォルトの動作では、Webhook と同じワークスペースでジョブがトリガーされます。

必要条件

既存のジョブ。
個人用アクセストークン。アクセストークンはMLflow サービスでのみ読み取ることができ、Databricks 内のModel RegistryAPI ユーザーが返すことはできません。

注記

自動化されたツール、システム、スクリプト、アプリで認証する際のセキュリティのベストプラクティスとして、Databricks では OAuth トークンを使用することをお勧めします。

personal access token authentication を使用する場合、 Databricks では、ワークスペースユーザーではなく、サービスプリンシパルに属する personal access token を使用することをお勧めします。サービスプリンシパルのトークンを作成するには、「サービスプリンシパルのトークンの管理」を参照してください。

ジョブレジストリ Webhook を作成する

Bash
$ curl -X POST -H "Authorization: Bearer <access-token>" -d \ '{"model_name": "<model-name>",
  "events": ["TRANSITION_REQUEST_CREATED"],
  "description": "Job webhook trigger",
  "status": "TEST_MODE",
  "job_spec": {
    "job_id": "1",
    "workspace_url": "https://my-databricks-workspace.com",
    "access_token": "dapi12345..."}}'
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/create

Python
from databricks_registry_webhooks import RegistryWebhooksClient, JobSpec

job_spec = JobSpec(
  job_id="1",
  workspace_url="https://my-databricks-workspace.com",
  access_token="dapi12345..."
)
job_webhook = RegistryWebhooksClient().create_webhook(
  model_name="<model-name>",
  events=["TRANSITION_REQUEST_CREATED"],
  job_spec=job_spec,
  description="Job webhook trigger",
  status="TEST_MODE"
)

レスポンス

{"webhook": {
   "id":"1234567891",
   "creation_timestamp":1591440826026,
   "last_updated_timestamp":1591440826026,
   "status":"TEST_MODE",
   "events":["TRANSITION_REQUEST_CREATED"],
   "job_spec": {
     "job_id": "1",
     "workspace_url": "https://my-databricks-workspace.com"
}}}

Databricks Terraform プロバイダーと databricks_mlflow_webhook を使用してジョブレジストリ Webhook を作成することもできます。

レジストリのウェブフックの例を一覧表示

Bash
$ curl -X GET -H "Authorization: Bearer <access-token>" -d \ '{"model_name": "<model-name>"}'
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/list

Python
from databricks_registry_webhooks import RegistryWebhooksClient

webhooks_list = RegistryWebhooksClient().list_webhooks(model_name="<model-name>")

レスポンス

{"webhooks": [{
   "id":"1234567890",
   "creation_timestamp":1571440826026,
   "last_updated_timestamp":1582768296651,
   "status": "ACTIVE",
   "events":["MODEL_VERSION_CREATED"],
   "http_url_spec": {
     "url": "https://hooks.slack.com/services/...",
     "enable_ssl_verification": True
}},
{
   "id":"1234567891",
   "creation_timestamp":1591440826026,
   "last_updated_timestamp":1591440826026,
   "status":"TEST_MODE",
   "events":["TRANSITION_REQUEST_CREATED"],
   "job_spec": {
     "job_id": "1",
     "workspace_url": "https://my-databricks-workspace.com"
}}]}

Workspace Model Registry Webhook

Webhook イベント

Webhook の種類

ウェブフックペイロード

ジョブレジストリ Webhook ペイロード

シングルタスクジョブ

ノートブック and Python wheel ジョブ

Python、JAR、Spark Submit ジョブ

その他すべてのジョブ

マルチタスクジョブ

ペイロードの例

出来事： `MODEL_VERSION_TRANSITIONED_STAGE`

出来事： `MODEL_VERSION_TAG_SET`

出来事： `COMMENT_CREATED`

安全

クライアントの検証

HTTP レジストリ Webhook の認証ヘッダー

ジョブレジストリ Webhook の IP 許可リスト

監査ログ

Webhook トリガー監査ログ

例

HTTP レジストリ Webhook ワークフローの例

1. Webhook を作成する

2. Webhook をテストする

3. Webhook をアクティブステータスに更新します

4. Webhook を削除する

ジョブレジストリ Webhook ワークフローの例

必要条件

ジョブレジストリ Webhook を作成する

レジストリのウェブフックの例を一覧表示

ノートブック

MLflow Model Registry webhooks REST API サンプルノートブック

MLflow Model Registry webhooks Python client example ノートブック

Webhook イベント​

Webhook の種類​

ウェブフックペイロード​

ジョブレジストリ Webhook ペイロード​

シングルタスクジョブ​

ノートブック and Python wheel ジョブ​

Python、JAR、Spark Submit ジョブ​

その他すべてのジョブ​

マルチタスクジョブ​

ペイロードの例​

出来事： MODEL_VERSION_TRANSITIONED_STAGE​

出来事： MODEL_VERSION_TAG_SET​

出来事： COMMENT_CREATED​

安全​

クライアントの検証​

HTTP レジストリ Webhook の認証ヘッダー​

ジョブレジストリ Webhook の IP 許可リスト​

監査ログ​

Webhook トリガー監査ログ​

例​

HTTP レジストリ Webhook ワークフローの例​

1. Webhook を作成する​

2. Webhook をテストする​

3. Webhook をアクティブ ステータスに更新します​

4. Webhook を削除する​

ジョブレジストリ Webhook ワークフローの例​

必要条件​

ジョブレジストリ Webhook を作成する​

レジストリのウェブフックの例を一覧表示​

ノートブック​

MLflow Model Registry webhooks REST API サンプル ノートブック

MLflow Model Registry webhooks Python client example ノートブック

Webhook イベント

Webhook の種類

ウェブフックペイロード

ジョブレジストリ Webhook ペイロード

シングルタスクジョブ

ノートブック and Python wheel ジョブ

Python、JAR、Spark Submit ジョブ

その他すべてのジョブ

マルチタスクジョブ

ペイロードの例

出来事： `MODEL_VERSION_TRANSITIONED_STAGE`

出来事： `MODEL_VERSION_TAG_SET`

出来事： `COMMENT_CREATED`

安全

クライアントの検証

HTTP レジストリ Webhook の認証ヘッダー

ジョブレジストリ Webhook の IP 許可リスト

監査ログ

Webhook トリガー監査ログ

例

HTTP レジストリ Webhook ワークフローの例

1. Webhook を作成する

2. Webhook をテストする

3. Webhook をアクティブステータスに更新します

4. Webhook を削除する

ジョブレジストリ Webhook ワークフローの例

必要条件

ジョブレジストリ Webhook を作成する

レジストリのウェブフックの例を一覧表示

ノートブック

MLflow Model Registry webhooks REST API サンプルノートブック