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 ペイロードがあります。
{
"job_id": 1234567890,
"notebook_params": {
"event_message": "<Webhook Payload>"
}
}
Python、JAR、Spark Submit ジョブ
Python、JAR、および Spark の送信ジョブには、パラメーター リストを含む JSON ペイロードがあります。
{
"job_id": 1234567890,
"python_params": ["<Webhook Payload>"]
}
その他すべてのジョブ
他のすべてのタイプのジョブには、パラメーターのない JSON ペイロードがあります。
{
"job_id": 1234567890
}
マルチタスクジョブ
マルチタスク ジョブには、さまざまなタスクの種類のすべてのパラメーターがアカウントに設定された 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 エンコード部分を使用してシークレット検証を実行することをお勧めします。 ホスト名の検証を無効にすると、要求が意図しないホストに悪意を持ってルーティングされるリスクが高まります。
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 を指すことができます。
$ 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
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 から受信した状態コードと本文を返します。
$ curl -X POST -H "Authorization: Bearer <access-token>" -d \
'{"id": "1234567890"}' \
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/test
from databricks_registry_webhooks import RegistryWebhooksClient
http_webhook = RegistryWebhooksClient().test_webhook(
id="1234567890"
)
レスポンス
{
"status":200,
"body":"OK"
}
3. Webhook をアクティブ ステータスに更新します
実際のイベントに対して Webhook を有効にするには、update 呼び出しを使用してそのステータスを ACTIVE
に設定し、これを使用して他のプロパティを変更することもできます。
$ curl -X PATCH -H "Authorization: Bearer <access-token>" -d \
'{"id": "1234567890", "status": "ACTIVE"}' \
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/update
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
に設定するか (上記と同様の更新コマンドを使用)、削除します。
$ curl -X DELETE -H "Authorization: Bearer <access-token>" -d \
'{"id": "1234567890"}' \
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/delete
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 を作成する
$ 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
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 を作成することもできます。
レジストリのウェブフックの例を一覧表示
$ curl -X GET -H "Authorization: Bearer <access-token>" -d \ '{"model_name": "<model-name>"}'
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/list
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"
}}]}