Webhooks do Registro do Modelo de Espaço de Trabalho

Artigo
12/11/2024

Importante

Esta funcionalidade está em Pré-visualização Pública.

Os Webhooks permitem que você ouça eventos do Registro do Modelo de Espaço de Trabalho para que suas integrações possam acionar ações automaticamente. Você pode usar webhooks para automatizar e integrar seu pipeline de aprendizado de máquina com ferramentas e fluxos de trabalho de CI/CD existentes. Por exemplo, você pode acionar compilações de CI quando uma nova versão de modelo é criada ou notificar os membros da equipe por meio do Slack sempre que uma transição de modelo para produção for solicitada.

Webhooks estão disponíveis através da API REST do Databricks ou do cliente databricks-registry-webhooks Python no PyPI.

Nota

Webhooks não estão disponíveis quando você usa modelos no catálogo Unity. Para obter uma alternativa, consulte Posso usar solicitações de transição de estágio ou acionar webhooks em eventos?. Não há suporte para o envio de webhooks para pontos de extremidade privados (pontos de extremidade que não são acessíveis a partir da Internet pública).

Eventos Webhook

Você pode especificar um webhook para acionar um ou mais destes eventos:

MODEL_VERSION_CREATED: Uma nova versão do modelo foi criada para o modelo associado.
MODEL_VERSION_TRANSITIONED_STAGE: O estágio de uma versão do modelo foi alterado.
TRANSITION_REQUEST_CREATED: Um usuário solicitou que o estágio de uma versão do modelo fosse transferido.
COMMENT_CREATED: Um usuário escreveu um comentário sobre um modelo registrado.
REGISTERED_MODEL_CREATED: Foi criado um novo modelo registado. Esse tipo de evento só pode ser especificado para um webhook em todo o Registro, que pode ser criado não especificando um nome de modelo na solicitação de criação.
MODEL_VERSION_TAG_SET: Um usuário define uma tag na versão do modelo.
MODEL_VERSION_TRANSITIONED_TO_STAGING: Uma versão do modelo foi transferida para o preparo.
MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: Uma versão do modelo foi transferida para a produção.
MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: Uma versão do modelo foi arquivada.
TRANSITION_REQUEST_TO_STAGING_CREATED: Um usuário solicitou que uma versão do modelo fosse transferida para o preparo.
TRANSITION_REQUEST_TO_PRODUCTION_CREATED: Um usuário solicitou que uma versão do modelo fosse transferida para a produção.
TRANSITION_REQUEST_TO_ARCHIVED_CREATED: Um usuário solicitou que uma versão do modelo fosse arquivada.

Tipos de webhooks

Existem dois tipos de webhooks com base em seus alvos de gatilho:

Webhooks com pontos de extremidade HTTP (webhooks de registro HTTP): Envie gatilhos para um ponto de extremidade HTTP.
Webhooks com gatilhos de trabalho (webhooks de registro de trabalho): acione um trabalho em um espaço de trabalho do Azure Databricks. Se a listagem de permissões de IP estiver habilitada no espaço de trabalho do trabalho, você deverá permitir a lista dos IPs do espaço de trabalho do registro modelo. Consulte IP allowlisting para webhooks de registro de trabalho para obter mais informações.

Há também dois tipos de webhooks com base em seu escopo, com diferentes requisitos de controle de acesso:

Webhooks específicos do modelo: O webhook aplica-se a um modelo registado específico. Você deve ter permissões CAN MANAGE no modelo registrado para criar, modificar, excluir ou testar webhooks específicos do modelo.
Webhooks em todo o Registro: O webhook é acionado por eventos em qualquer modelo registrado no espaço de trabalho, incluindo a criação de um novo modelo registrado. Para criar um webhook em todo o Registro, omita o model_name campo na criação. Você deve ter permissões de administrador do espaço de trabalho para criar, modificar, excluir ou testar webhooks em todo o Registro.

Carga útil Webhook

Cada gatilho de evento tem campos mínimos incluídos na carga útil para a solicitação de saída para o ponto de extremidade do webhook.

Informações confidenciais, como a localização do caminho do artefato, são excluídas. Os usuários e entidades com ACLs apropriadas podem usar APIs de cliente ou REST para consultar o Registro Modelo para obter essas informações.
As cargas úteis não são encriptadas. Consulte Segurança para obter informações sobre como validar que o Azure Databricks é a origem do webhook.
O campo facilita a integração com o text Slack. Para enviar uma mensagem do Slack, forneça um ponto de extremidade do webhook do Slack como a URL do webhook.

Carga útil do webhook do registro de trabalho

A carga útil para um webhook de registro de trabalho depende do tipo de trabalho e é enviada para o jobs/run-now ponto de extremidade no espaço de trabalho de destino.

Trabalhos de tarefa única

Os trabalhos de tarefa única têm uma das três cargas úteis com base no tipo de tarefa.

Trabalhos de roda de notebook e Python

Os trabalhos de roda de notebook e Python têm uma carga JSON com um dicionário de parâmetros que contém um campo event_message.

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

Trabalhos de envio de Python, JAR e Spark

Os trabalhos de envio Python, JAR e Spark têm uma carga JSON com uma lista de parâmetros.

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

Todos os outros trabalhos

Todos os outros tipos de trabalhos têm uma carga JSON sem parâmetros.

{
  "job_id": 1234567890
}

Trabalhos multitarefas

Os trabalhos multitarefa têm uma carga JSON com todos os parâmetros preenchidos para levar em conta diferentes tipos de tarefas.

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

Exemplo de cargas úteis

Evento: `MODEL_VERSION_TRANSITIONED_STAGE`

Response

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

Evento: `MODEL_VERSION_TAG_SET`

Response

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

Evento: `COMMENT_CREATED`

Response

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

Segurança

Por segurança, o Azure Databricks inclui a X-Databricks-Signature no cabeçalho calculado a partir da carga útil e a chave secreta compartilhada associada ao webhook usando o HMAC com algoritmo SHA-256.

Além disso, você pode incluir um cabeçalho de Autorização padrão na solicitação de saída especificando um no HttpUrlSpec webhook.

Verificação do cliente

Se um segredo compartilhado for definido, o destinatário da carga útil deverá verificar a origem da solicitação HTTP usando o segredo compartilhado para codificar HMAC a carga e, em seguida, comparando o valor codificado com o X-Databricks-Signature do cabeçalho. Isso é particularmente importante se a validação do certificado SSL estiver desabilitada (ou seja, se o enable_ssl_verification campo estiver definido como false).

Nota

enable_ssl_verification é true por defeito. Para certificados autoassinados, esse campo deve ser false, e o servidor de destino deve desabilitar a validação de certificado.

Para fins de segurança, o Databricks recomenda que você execute a validação secreta com a parte codificada pelo HMAC da carga útil. Se você desabilitar a validação de nome de host, aumentará o risco de que uma solicitação possa ser roteada maliciosamente para um host não intencional.

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

Cabeçalho de autorização para webhooks de registro HTTP

Se um cabeçalho de Autorização estiver definido, os clientes deverão verificar a origem da solicitação HTTP verificando o token de portador ou as credenciais de autorização no cabeçalho de Autorização.

IP allowlisting para webhooks de registro de trabalho

Para usar um webhook que aciona tarefas executadas em um espaço de trabalho diferente que tenha a listagem de permissões de IP habilitada, você deve permitir a lista de IP NAT da região onde o webhook está localizado para aceitar solicitações de entrada.

Se o webhook e o trabalho estiverem no mesmo espaço de trabalho, você não precisará adicionar nenhum IPs à sua lista de permissões.

Se o seu trabalho estiver localizado em uma região multilocatária do Azure, consulte Endereços de plano de controle do Azure Databricks. Para todas as outras regiões, entre em contato com a equipe da sua conta para identificar os IPs que você precisa permitir.

Registo de auditoria

Se o log de auditoria estiver habilitado para seu espaço de trabalho, os seguintes eventos serão incluídos nos logs de auditoria:

Criar webhook
Atualizar webhook
Lista webhook
Excluir webhook
Webhook de teste
Gatilho Webhook

Log de auditoria de gatilho Webhook

Para webhooks com pontos de extremidade HTTP, a solicitação HTTP enviada para a URL especificada para o webhook juntamente com a URL e enable_ssl_verification os valores são registrados.

Para webhooks com gatilhos de trabalho, os job_id valores e workspace_url são registrados.

Exemplos

Esta secção inclui:

Exemplo de fluxo de trabalho de webhook de registro HTTP.
exemplo de fluxo de trabalho webhook de registro de trabalho.
listar exemplo de webhooks.
dois blocos de anotações de exemplo: um ilustrando a API REST e outro ilustrando o cliente Python.

Fluxo de trabalho de exemplo de webhook de registro HTTP

1. Crie um webhook

Quando um ponto de extremidade HTTPS estiver pronto para receber a solicitação de evento webhook, você poderá criar um webhook usando a API REST Webhooks Databricks. Por exemplo, o URL do webhook pode apontar para o Slack para postar mensagens em um canal.

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

Response

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

Você também pode criar um webhook de registro HTTP com o provedor Databricks Terraform e databricks_mlflow_webhook.

2. Teste o webhook

O webhook anterior foi criado no TEST_MODE, para que um evento fictício possa ser acionado para enviar uma solicitação para a URL especificada. No entanto, o webhook não é acionado em um evento real. O ponto de extremidade de teste retorna o código de status recebido e o corpo da URL especificada.

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

Response

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

3. Atualize o webhook para o status ativo

Para habilitar o webhook para eventos reais, defina seu status por ACTIVE meio de uma chamada de atualização, que também pode ser usada para alterar qualquer uma de suas outras propriedades.

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

Response

{"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. Exclua o webhook

Para desativar o webhook, defina seu status como DISABLED (usando um comando de atualização semelhante ao acima) ou exclua-o.

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

Response

{}

Fluxo de trabalho de exemplo de webhook de registro de trabalho

O fluxo de trabalho para gerenciar webhooks de registro de trabalho é semelhante aos webhooks de registro HTTP, com a única diferença sendo o job_spec campo que substitui o http_url_spec campo.

Com webhooks, você pode acionar trabalhos no mesmo espaço de trabalho ou em um espaço de trabalho diferente. O espaço de trabalho é especificado usando o parâmetro workspace_urlopcional . Se não workspace_url estiver presente, o comportamento padrão é acionar um trabalho no mesmo espaço de trabalho que o webhook.

Requisitos

Um trabalho existente.
Um token de acesso pessoal. Observe que os tokens de acesso só podem ser lidos pelo serviço MLflow e não podem ser retornados por usuários do Azure Databricks na API do Registro Modelo.

Nota

Como prática recomendada de segurança, quando você se autentica com ferramentas, sistemas, scripts e aplicativos automatizados, o Databricks recomenda que você use tokens de acesso pessoal pertencentes a entidades de serviço em vez de usuários do espaço de trabalho. Para criar tokens para entidades de serviço, consulte Gerenciar tokens para uma entidade de serviço.

Criar um webhook de registro de trabalho

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

Response

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

Você também pode criar um webhook de registro de trabalho com o provedor Databricks Terraform e databricks_mlflow_webhook.

Exemplo de webhooks de registro de lista

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

Response

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

Partilhar via

Webhooks do Registro do Modelo de Espaço de Trabalho

Eventos Webhook

Tipos de webhooks

Carga útil Webhook

Carga útil do webhook do registro de trabalho

Trabalhos de tarefa única

Trabalhos de roda de notebook e Python

Trabalhos de envio de Python, JAR e Spark

Todos os outros trabalhos

Trabalhos multitarefas

Exemplo de cargas úteis

Evento: `MODEL_VERSION_TRANSITIONED_STAGE`

Evento: `MODEL_VERSION_TAG_SET`

Evento: `COMMENT_CREATED`

Segurança

Verificação do cliente

Cabeçalho de autorização para webhooks de registro HTTP

IP allowlisting para webhooks de registro de trabalho

Registo de auditoria

Log de auditoria de gatilho Webhook

Exemplos

Fluxo de trabalho de exemplo de webhook de registro HTTP

1. Crie um webhook

2. Teste o webhook

3. Atualize o webhook para o status ativo

4. Exclua o webhook

Fluxo de trabalho de exemplo de webhook de registro de trabalho

Requisitos

Criar um webhook de registro de trabalho

Exemplo de webhooks de registro de lista

Notebooks

Exemplo de webhooks da API REST do MLflow Model Registry Notebook de exemplo

Webhooks do Registro do Modelo MLflow Notebook de exemplo de cliente Python

Comentários

Recursos adicionais

Partilhar via

Webhooks do Registro do Modelo de Espaço de Trabalho

Eventos Webhook

Tipos de webhooks

Carga útil Webhook

Carga útil do webhook do registro de trabalho

Trabalhos de tarefa única

Trabalhos de roda de notebook e Python

Trabalhos de envio de Python, JAR e Spark

Todos os outros trabalhos

Trabalhos multitarefas

Exemplo de cargas úteis

Evento: MODEL_VERSION_TRANSITIONED_STAGE

Evento: MODEL_VERSION_TAG_SET

Evento: COMMENT_CREATED

Segurança

Verificação do cliente

Cabeçalho de autorização para webhooks de registro HTTP

IP allowlisting para webhooks de registro de trabalho

Registo de auditoria

Log de auditoria de gatilho Webhook

Exemplos

Fluxo de trabalho de exemplo de webhook de registro HTTP

1. Crie um webhook

2. Teste o webhook

3. Atualize o webhook para o status ativo

4. Exclua o webhook

Fluxo de trabalho de exemplo de webhook de registro de trabalho

Requisitos

Criar um webhook de registro de trabalho

Exemplo de webhooks de registro de lista

Notebooks

Exemplo de webhooks da API REST do MLflow Model Registry Notebook de exemplo

Webhooks do Registro do Modelo MLflow Notebook de exemplo de cliente Python

Comentários

Recursos adicionais

Evento: `MODEL_VERSION_TRANSITIONED_STAGE`

Evento: `MODEL_VERSION_TAG_SET`

Evento: `COMMENT_CREATED`