Webhooks voor werkruimtemodelregister

Met Webhooks kunt u luisteren naar register-gebeurtenissen voor werkruimtemodellen, zodat uw integraties automatisch acties kunnen activeren. U kunt webhooks gebruiken om uw machine learning-pijplijn te automatiseren en te integreren met bestaande CI/CD-hulpprogramma's en werkstromen. U kunt bijvoorbeeld CI-builds activeren wanneer er een nieuwe modelversie wordt gemaakt of uw teamleden op de hoogte stellen via Slack telkens wanneer een modelovergang naar productie wordt aangevraagd.

Webhooks zijn beschikbaar via de Databricks REST API of de Python-client databricks-registry-webhooks op PyPI.

Webhook-gebeurtenissen

U kunt een webhook opgeven die moet worden geactiveerd op een of meer van deze gebeurtenissen:

• MODEL_VERSION_CREATED: er is een nieuwe modelversie gemaakt voor het bijbehorende model.
• MODEL_VERSION_TRANSITIONED_STAGE: de fase van een modelversie is veranderd.
• TRANSITION_REQUEST_CREATED: Een gebruiker heeft gevraagd om de fase van een modelversie over te schakelen.
• COMMENT_CREATED: Een gebruiker heeft een opmerking over een geregistreerd model geschreven.
• REGISTERED_MODEL_CREATED: Er is een nieuw geregistreerd model gemaakt. Dit gebeurtenistype kan alleen worden opgegeven voor een webhook voor het hele register, dat kan worden gemaakt door geen modelnaam op te geven in de aanvraag voor maken.
• MODEL_VERSION_TAG_SET: Een gebruiker stelt een tag in voor de modelversie.
• MODEL_VERSION_TRANSITIONED_TO_STAGING: er is een modelversie overgezet naar staging.
• MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: Er is een modelversie overgezet naar productie.
• MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: Er is een modelversie gearchiveerd.
• TRANSITION_REQUEST_TO_STAGING_CREATED: Een gebruiker heeft gevraagd om een modelversie over te schakelen naar staging.
• TRANSITION_REQUEST_TO_PRODUCTION_CREATED: Een gebruiker heeft gevraagd om een modelversie over te schakelen naar productie.
• TRANSITION_REQUEST_TO_ARCHIVED_CREATED: Een gebruiker heeft gevraagd om een modelversie te archiveren.

Typen webhooks

Er zijn twee soorten webhooks op basis van hun triggerdoelen:

• Webhooks met HTTP-eindpunten (HTTP-registerwebhooks): triggers verzenden naar een HTTP-eindpunt.
• Webhooks met taaktriggers (taakregisterwebhooks): een taak activeren in een Azure Databricks-werkruimte. Als IP-acceptatielijst is ingeschakeld in de werkruimte van de taak, moet u de ip-adressen van de werkruimte van het modelregister toestaan. Zie ip-acceptatielijst voor webhooks voor taakregisters voor meer informatie.

Er zijn ook twee soorten webhooks op basis van hun bereik, met verschillende vereisten voor toegangsbeheer:

• Modelspecifieke webhooks: De webhook is van toepassing op een specifiek geregistreerd model. U moet over CAN MANAGE-machtigingen voor het geregistreerde model beschikken om webhooks te maken, te wijzigen, te verwijderen of te testen.
• Registerbrede webhooks: de webhook wordt geactiveerd door gebeurtenissen op elk geregistreerd model in de werkruimte, inclusief het maken van een nieuw geregistreerd model. Als u een webhook voor het gehele register wilt maken, laat het model_name veld weg tijdens de creatie. U moet beschikken over beheerdersmachtigingen voor werkruimten om webhooks voor het hele register te maken, te wijzigen, te verwijderen of te testen.

Webhook payload

Elke gebeurtenistrigger heeft minimale velden opgenomen in de payload voor het uitgaande verzoek naar de webhook-eindpunt.

• Gevoelige informatie, zoals de locatie van het artefactpad, wordt uitgesloten. Gebruikers en principals met de juiste ACL's kunnen client- of REST API's gebruiken om een query uit te voeren op het modelregister voor deze informatie.
• Nettoladingen worden niet versleuteld. Zie Beveiliging voor informatie over hoe u kunt valideren dat Azure Databricks de bron van de webhook is.
• Het text veld vereenvoudigt slack-integratie. Als u een Slack-bericht wilt verzenden, geeft u een Slack-webhookeindpunt op als de URL van de webhook.

Nettolading taakregisterwebhook

De payload voor een webhook voor het taakregister is afhankelijk van het type taak en wordt verzonden naar het jobs/run-now eindpunt in de specifieke werkruimte.

Taken met één taak

Enkelvoudige taken hebben een van de drie pakketinhouden afhankelijk van het taaktype.

Notebook- en Python-wieltaken

Notebook- en Python-wieltaken hebben een JSON-payload met een parameterwoordenlijst die een veld event_message bevat.

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

Python-, JAR- en Spark Submit-taken

Python-, JAR- en Spark-jobinzendingen hebben een JSON-belasting met een parameterslijst.

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

Alle andere werkzaamheden

Alle andere typen taken hebben een JSON-nettolading zonder parameters.

{
  "job_id": 1234567890
}

Taken met meerdere taken

Werkzaamheden met meerdere taken hebben een JSON-payload waarin alle parameters zijn ingevuld om rekening te houden met verschillende soorten taken.

{
  "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>"]
}

Voorbeeld van nettoladingen

gebeurtenis: MODEL_VERSION_TRANSITIONED_STAGE

Antwoord

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."
}

gebeurtenis: MODEL_VERSION_TAG_SET

Antwoord

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."
}

gebeurtenis: COMMENT_CREATED

Antwoord

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."
}

Beveiliging

Voor beveiliging bevat Azure Databricks de X-Databricks-Signature in de header die wordt berekend op basis van de nettolading en de gedeelde geheime sleutel die is gekoppeld aan de webhook met behulp van het HMAC met sha-256-algoritme.

Daarnaast kunt u een standaardautorisatieheader opnemen in de uitgaande aanvraag door er een op te geven in de HttpUrlSpec webhook.

Klantverificatie

Als een gedeeld geheim is ingesteld, moet de ontvanger van de payload de bron van de HTTP-aanvraag verifiëren door de payload met het gedeelde geheim te HMAC-coderen en vervolgens de gecodeerde waarde te vergelijken met de X-Databricks-Signature uit de header. Dit is met name belangrijk als ssl-certificaatvalidatie is uitgeschakeld (dat wil gezegd, als het enable_ssl_verification veld is ingesteld op false).

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.')

Autorisatieheader voor HTTP-registerwebhooks

Als een autorisatie-header is ingesteld, moeten clients de bron van de HTTP-aanvraag controleren door het bearer-token of de autorisatiereferenties in de autorisatieheader te verifiëren.

IP-acceptatielijst voor webhooks voor taakregister

Als u een webhook wilt gebruiken die taakuitvoeringen activeert in een andere werkruimte die IP-toegangscontrolelijst inschakelt, moet u het NAT-IP-adres van de regio waar de webhook zich bevindt op de toegangscontrolelijst plaatsen om binnenkomende verzoeken te accepteren.

Als de webhook en de taak zich in dezelfde werkruimte bevinden, hoeft u geen IP-adressen toe te voegen aan uw acceptatielijst.

Als uw taak zich in een Azure-regio met meerdere tenants bevindt, raadpleegt u IP-adressen en domeinen voor Azure Databricks-services en -assets. Neem voor alle andere regio's contact op met uw accountteam om de IP-adressen te identificeren die u nodig hebt voor de acceptatielijst.

Controlegebeurtenissen vastleggen

Als auditlogboekregistratie is ingeschakeld voor uw werkruimte, worden de volgende gebeurtenissen opgenomen in de auditlogboeken:

• Webhook maken
• Webhook bijwerken
• Webhooks weergeven
• Webhook verwijderen
• Webhook testen
• Webhooktrigger

Auditlogboekregistratie voor webhooktriggers

Voor webhooks met HTTP-eindpunten wordt de HTTP-aanvraag die is verzonden naar de URL die is opgegeven voor de webhook, samen met de URL en enable_ssl_verification waarden vastgelegd.

Voor webhooks met taaktriggers worden de job_id en workspace_url waarden vastgelegd.

Voorbeelden

Dit gedeelte bevat:

• Voorbeeld van een http-registerwebhookwerkstroom.
• voorbeeld van webhookwerkstroom voor taakregisters.
• voorbeeld van lijstwebhooks.
• twee voorbeeldnotebooks: één die de REST API illustreert en één die de Python-client illustreert.

Voorbeeldwerkstroom voor http-registerwebhook

1. Een webhook maken

Wanneer een HTTPS-eindpunt gereed is om de aanvraag voor de webhook-gebeurtenis te ontvangen, kunt u een webhook maken met behulp van de Webhooks Databricks REST API. De URL van de webhook kan bijvoorbeeld verwijzen naar Slack om berichten naar een kanaal te posten.

$ 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"
)

Antwoord

{"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
}}}

U kunt ook een HTTP-registerwebhook maken met de Databricks Terraform-provider en databricks_mlflow_webhook.

2. De webhook testen

De vorige webhook is gemaakt in TEST_MODE, zodat een mockgebeurtenis kan worden geactiveerd om een aanvraag naar de opgegeven URL te verzenden. De webhook wordt echter niet geactiveerd voor een reële gebeurtenis. Het testeindpunt retourneert de ontvangen statuscode en hoofdtekst van de opgegeven 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"
)

Antwoord

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

3. Werk de webhook bij naar de actieve status

Als u de webhook voor echte gebeurtenissen wilt inschakelen, stelt u de status ACTIVE ervan in via een updateaanroep, die ook kan worden gebruikt om een van de andere eigenschappen te wijzigen.

$ 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"
)

Antwoord

{"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. De webhook verwijderen

Als u de webhook wilt uitschakelen, stelt u de status DISABLED ervan in op (met behulp van een vergelijkbare updateopdracht als hierboven) of verwijdert u deze.

$ 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"
)

Antwoord

{}

Voorbeeldwerkstroom van webhook voor taakregister

De werkstroom voor het beheren van webhooks van het taakregister is vergelijkbaar met HTTP-registerwebhooks, met als enige verschil dat het job_spec-veld het http_url_spec-veld vervangt.

Met webhooks kunt u taken in dezelfde werkruimte of in een andere werkruimte activeren. De werkruimte wordt opgegeven met behulp van de optionele parameter workspace_url. Als er geen workspace_url aanwezig is, is het standaardgedrag het activeren van een taak in dezelfde werkruimte als de webhook.

Vereisten

• Een bestaande taak.
• Een persoonlijk toegangstoken. Toegangstokens kunnen alleen worden gelezen door de MLflow-service en kunnen niet worden geretourneerd door Azure Databricks-gebruikers in de Model Registry-API.

Een webhook voor het taakregister maken

$ 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"
)

Antwoord

{"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"
}}}

U kunt ook een webhook voor het taakregister maken met de Databricks Terraform-provider en databricks_mlflow_webhook.

Voorbeeld van registerwebhooks weergeven

$ 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>")

Antwoord

{"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"
}}]}

Notitieboeken

MLflow Model Registry-webhooks REST API-voorbeeldnotebook

Notitieblok ophalen

Voorbeeldnotebook voor MLflow Model Registry-webhooks Python-client

Notitieblok ophalen