Pular para o conteúdo principal

Webhooks do Workspace Model Registry

info

Visualização

Esse recurso está em Public Preview.

Os webhooks permitem que o senhor ouça os eventos do Workspace Model Registry para que suas integrações possam acionar ações automaticamente. O senhor pode usar webhooks para automatizar e integrar seu aprendizado de máquina pipeline com as ferramentas CI/CD e o fluxo de trabalho existentes. Por exemplo, você pode acionar compilações de CI quando uma nova versão do modelo é criada ou notificar os membros da sua equipe pelo Slack sempre que uma transição de modelo para produção for solicitada.

Os webhooks estão disponíveis por meio da API REST da Databricks ou do cliente Python databricks-registry-webhooks no PyPI.

nota

Os webhooks não estão disponíveis quando o senhor usa Models no Unity Catalog. 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 endpoints privados (endpoints que não são acessíveis pela Internet pública).

Eventos de webhook​

Você pode especificar um webhook para acionar um ou mais desses 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: Um novo modelo registrado foi criado . Esse tipo de evento só pode ser especificado para um webhook de todo o registro, que pode ser criado sem especificar um nome de modelo na solicitação de criação.
  • MODEL_VERSION_TAG_SET: Um usuário definiu uma tag na versão do modelo.
  • MODEL_VERSION_TRANSITIONED_TO_STAGING: Uma versão do modelo foi transferida para teste .
  • MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: Uma versão do modelo foi transferida para 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 teste.
  • TRANSITION_REQUEST_TO_PRODUCTION_CREATED: Um usuário solicitou que uma versão do modelo fosse transferida para 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 endpoint HTTP (webhooks de registro HTTP) : Envie acionadores para um HTTP endpoint.
  • Webhooks com acionadores de trabalho (webhooks de registro de trabalho) : Acione um Job em um Databricks workspace. Se a lista de permissões de IP estiver ativada no site workspace do trabalho, o senhor deverá permitir os IPs workspace do registro de modelo. Consulte IP allowlisting for Job registry webhooks para obter mais informações.

Também existem dois tipos de webhooks com base em seu escopo, com diferentes requisitos de controle de acesso:

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

Carga útil do webhook​

Cada acionador de evento tem campos mínimos incluídos no payload da solicitação de saída para o endpoint do webhook.

  • Informações confidenciais, como localização do caminho do artefato, são excluídas. Usuários e principais com ACLs apropriados podem usar o cliente ou APIs REST para query o Model Registry para esta informação.
  • As cargas não são criptografadas. Consulte Segurança para obter informações sobre como validar que Databricks é a fonte do webhook.
  • O campo text facilita a integração com o Slack. Para enviar uma mensagem do Slack, forneça um webhook do Slack endpoint como URL do webhook.

Job carga útil do webhook de registro​

A carga útil de um webhook de registro de trabalho depende do tipo de trabalho e é enviada para jobs/run-now endpoint no destino workspace.

Trabalho de tarefa única​

O Job de tarefa única tem uma das três cargas úteis com base no tipo de tarefa.

Notebook e Job Python wheel​

Job de Notebook e Python wheel têm uma carga útil JSON com um dicionário de parâmetros que contém um campo event_message.

JSON
{
  "job_id": 1234567890,
  "notebook_params": {
    "event_message": "<Webhook Payload>"
  }
}
Python, JAR, e Spark Enviar trabalho​

Python, JAR e Spark enviam trabalhos que têm um payload JSON com uma lista de parâmetros.

JSON
{
  "job_id": 1234567890,
  "python_params": ["<Webhook Payload>"]
}
Todos os outros empregos​

Todos os outros tipos de Job têm um payload JSON sem parâmetros.

JSON
{
  "job_id": 1234567890
}

Trabalho multitarefa​

O trabalho multitarefa tem uma carga útil JSON com todos os parâmetros preenchidos em account para diferentes tipos de tarefa.

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

Exemplos de cargas úteis​

evento: MODEL_VERSION_TRANSITIONED_STAGE​

Resposta

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​

Resposta

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​

Resposta

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​

Para fins de segurança, o site Databricks inclui o X-Databricks-Signature no cabeçalho computado a partir da carga útil e o segredo de chave compartilhada associado ao webhook usando o HMAC com o 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 do 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 a carga em HMAC 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 desativada (ou seja, se o campo enable_ssl_verification estiver definido como false).

nota

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

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

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

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

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

Lista de permissões de IP para webhooks de registro de trabalho​

Para usar um webhook que aciona a execução de um trabalho em um site diferente workspace que tenha a lista de permissões de IP ativada, o senhor deve permitir que o IP NAT da região onde o webhook está localizado aceite solicitações de entrada.

Se o webhook e o Job estiverem no mesmo workspace, o senhor não precisará adicionar nenhum IP à sua lista de permissões.

Entre em contato com a equipe da sua conta para identificar os IPs que precisam ser incluídos na lista de permissões.

Registro de auditoria​

Se o registro de auditoria estiver ativado no site workspace, os seguintes eventos serão incluídos na auditoria logs:

  • Crie um webhook
  • Atualizar webhook
  • Listar webhook
  • Excluir webhook
  • Teste o webhook
  • Acionador de webhook

Registro de auditoria do Webhook aciona​

Para webhooks com endpoint HTTP, a solicitação HTTP enviada ao URL especificado para o webhook juntamente com o URL e os valores de enable_ssl_verification são registros.

Para webhooks com acionadores de trabalho, os valores job_id e workspace_url são logs.

Exemplos​

Esta seção inclui:

Exemplo de fluxo de trabalho de webhook de registro HTTP​

1. Crie um webhook​

Quando um HTTPS endpoint estiver pronto para receber a solicitação de evento do webhook, o senhor poderá criar um webhook usando os webhooks Databricks REST API. Por exemplo, o URL do webhook pode apontar para o Slack para publicar mensagens em um canal.

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

Resposta

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

Também é possível criar um webhook de registro HTTP com o provedor Databricks Terraform e databricks_mlflow_webhook.

2. Teste o webhook​

O webhook anterior foi criado em TEST_MODE, então um evento simulado pode ser acionado para enviar uma solicitação ao URL especificado. No entanto, o webhook não é acionado em um evento real. O teste endpoint retorna o código de status e o corpo recebidos do URL especificado.

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

Resposta

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

3. Atualize o webhook para o status ativo​

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

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

Resposta

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

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

Resposta

{}

Job exemplo de webhook de registro fluxo de trabalho​

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

Com webhooks, o senhor pode acionar o Job no mesmo workspace ou em um workspace diferente. O endereço workspace é especificado usando o parâmetro opcional workspace_url. Se nenhum workspace_url estiver presente, o comportamento do default é acionar um trabalho no mesmo workspace 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 pelos usuários do Databricks na API Model Registry.
nota

Como prática recomendada de segurança, ao se autenticar com ferramentas, sistemas, scripts e aplicativos automatizados, o Databricks recomenda que o senhor use o acesso pessoal tokens pertencente à entidade de serviço em vez dos usuários do workspace. Para criar tokens o site para uma entidade de serviço, consulte gerenciar tokens para uma entidade de serviço.

Criar um webhook de registro de trabalho​

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

Resposta

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

O senhor também pode criar um webhook de registro de trabalho com o provedorDatabricks Terraform e o databricks_mlflow_webhook.

Exemplo de webhooks de registro de listas​

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

Resposta

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

Caderno de anotações​

MLflow Model Registry webhooks REST API exemplo Notebook

Open notebook in new tab

MLflow Model Registry webhooks Python exemplo de cliente Notebook

Open notebook in new tab
Última atualização em