Automatize fluxos de trabalho de notebook com eventos de webhook

Um webhook é um mecanismo que permite que um aplicativo forneça a outros aplicativos informações sobre eventos. Os webhooks podem ser configurados nos níveis de organização e serviço para executar automaticamente um notebook quando ocorrerem eventos associados à sua organização ou serviços.

Automatize um notebook usando webhooks da organização

Como um administrador do ArcGIS Enterprise ou um usuário com o privilégio webhooks da Organização, você pode criar, gerenciar e configurar webhooks. Você pode configurar webhooks para executar automaticamente um notebook de sua propriedade quando ocorrerem eventos associados aos seus itens, grupos ou usuários. do ArcGIS Notebook Server atuam como o receptor da carga útil do webhook. Após um webhook ser ativado, uma solicitação HTTP é realizada para do ArcGIS Notebook Server para executar um notebook escolhido sem qualquer interação do usuário.

Anotação:

O número de notebooks em execução simultânea a partir de webhooks é limitado pela propriedade do sistema maxExecuteNotebookContainersPerNode nos do ArcGIS Notebook Server.

Criar um webhook da organização

Os webhooks podem ser administrados na página Configurações da sua organização. Utilize as seguintes etapas para criar um webhook:

1. Entre como administrador padrão ou papel personalizado com o privilégio de webhooks da organização.
2. Clique em Organização > Configurações > Webhooks..
3. Na seção Webhooks da organização, clique em Criar webhook.
4. Especifique um nome de webhook.
5. Selecione o tipo de evento que ativará o webhook.

   Por padrão, todos os tipos de eventos (Itens, Usuários, Grupos e Papéis) são considerados.

   Consulte Eventos ativadores suportados para obter mais informações.

6. Selecione Notebook como o tipo de carga útil.

   Anotação:

   Se a opção Notebook não estiver disponível, Notebook Server não foi configurado com seu portal. Se a opção Notebook estiver disponível, mas não puder ser selecionada, você não possui nenhum notebook disponível para configurar webhooks. Você deve ser proprietário de item do notebook que será usado para o webhook.

7. Selecione o notebook que será executado quando o webhook for ativado.
8. Opcionalmente, insira uma chave Secreta que será incluída na carga útil do webhook.

   Você também pode optar por usar valores aleatórios pré-gerados para a chave Secreta.

9. Clique em Criar webhook para salvar as configurações do webhook e criar um webhook.

Gerenciar webhooks da organização

Os webhooks podem ser administrados na página Configurações da sua organização. Use as seguintes etapas para gerenciar webhooks existentes:

1. Entre como administrador padrão ou papel personalizado com o privilégio de webhooks da Organização.
2. Clique em Organização > Configurações > Webhooks para ver uma lista de webhooks da organização criados por você e outros administradores de webhooks.

Você pode gerenciar seus webhooks existentes com as seguintes operações.

• Desativar webhook—Quando um webhook estiver em um estado ativo, clique em Ativo. Desativar o webhook impede que as cargas úteis sejam entregues quando o webhook for ativado.
• Ativar webhook—Quando um webhook estiver em um estado inativo, clique em Inativo. Após um webhook ser ativado, ele retomará a entrega de cargas úteis.
• Editar webhook—Clique no botão de opções no webhook e clique em Editar para atualizar seu webhook.
• Excluir webhook—Clique no botão de opções no webhook e clique emExcluir. Clique em Confirmar para excluir o webhook.

Modificar configurações avançadas do webhook da organização

Use as configurações de webhook Avançadas para alterar propriedades como o número de tentativas de entrega que podem ser feitas, notificações de tempo decorrido e propriedades de tempo limite de notificação para webhooks. Essas configurações avançadas serão aplicadas a todos os webhooks na sua organização. Para modificar as configurações avançadas do webhook, conclua as seguintes etapas:

1. Entre como administrador padrão ou papel personalizado com o privilégio de webhooks da Organização.
2. Clique em Organização > Configurações > Webhooks..
3. Na seção Webhooks da organização, clique em Configurações avançadas para modificar os valores padrão das propriedades avançadas do webhook.

Carga útil de webhooks da organização

Quando um notebook é executado por meio de um webhook, as informações de carga útil do webhook são injetadas automaticamente no notebook em uma célula inicial. Após injetadas, as informações fornecidas na carga útil do webhook podem ser usadas no notebook para fluxos de trabalho de automação adicionais.

Informações de carga útil do webhook incluídas em um notebook:

webhookPayload = {
    "properties": {
        "itemId": "<notebook_item_id>"
    },
    "events": [
        {
            "source": "<items | user | group | role>",
            "id": "<source_id>",
            "userId": "<user_id_of_member_triggered_webhook>",
            "when": 1742596800000,
            "operation": "<operation_triggered_webhook>",
            "properties": {"<operation_details>"},
            "username": "<username_of_member_triggered_webhook>"
        }
    ],
    "info": {
        "webhookId": "<webhook_id>",
        "portalURL": "<portal_url>",
        "webhookName": "<webhook_name>",
        "when": 1742596805000
    }
}

Automatize um notebook usando webhooks de serviço

Webhooks—incluindo aqueles para serviços de geoprocessamento assíncronos, serviços de feição e outros webhooks genéricos — podem acionar uma execução de notebook em resposta a eventos específicos. Os administradores podem registrar uma URL de receptor de webhook como URL de hook ou carga útil para esses webhooks. Quando um evento específico associado a um webhook é acionado, ele chamará automaticamente a URL do receptor do webhook do Notebook, iniciando a execução do notebook correspondente.

As seções a seguir descrevem como configurar um receptor webhook de notebook em do ArcGIS Notebook Server.

Crie e copie uma chave de API

Uma chave de API é um token de longa duração que autoriza um webhook de serviço a executar um item de notebook associado e acessar com segurança os recursos e funcionalidades do ArcGIS Enterprise necessários para a execução do notebook.

As chaves API são geradas usando credenciais de chave API, um tipo de item hospedado em sua organização. As credenciais da chave de API contêm configurações que permitem gerar chaves de API e gerenciar propriedades como seus privilégios e data de expiração. O processo de criação de credenciais de chave de API e uso de chaves de API em seu aplicativo é conhecido como autenticação de chave de API.

Para criar e copiar uma chave de API, conclua as seguintes etapas:

1. Entre no seu portal como usuário administrativo.
2. Clique na página Detalhes do item da chave de API.
3. Siga as etapas no tutorial Criar uma chave de API para saber como criar e copiar uma chave de API. Conceda os privilégios Criar e editar Notebooks, Criar, Atualizar e Excluir itens e, opcionalmente, conceda o privilégio Notebook avançado para ArcPy.

   Privilégios adicionais podem ser necessários dependendo dos fluxos de trabalho executados no notebook.

Registre um receptor de webhook de notebook

Para registrar um receptor webhook de notebook, conclua as seguintes etapas:

1. Entre no seu portal como um administrador.
2. Clique em Organização > Configurações > webhooks > Criar receptor webhook.
3. Digite um nome para o seu receptor de webhook.
4. Selecione o notebook que o receptor do webhook executará.
5. Insira uma chave secreta de 32 caracteres que será usada para garantir a origem do webhook.
6. Insira uma lista separada por vírgulas de cabeçalhos de assinatura que serão verificados para uma carga criptografada.
7. Insira o token da API com privilégios para acessar o item do notebook, privilégios Criar Notebook/Criar Notebook Avançado e quaisquer outros recursos de GIS no notebook.
8. Opcionalmente, insira parâmetros no formato JSON.
9. Clique em Criar receptor.

Crie um serviço de geoprocessamento assíncrono ou um webhook de serviço de feição

Para criar um serviço de geoprocessamento assíncrono ou um webhook de serviço de feição, conclua as seguintes etapas:

1. Use a URL do receptor de webhook, cabeçalhos secretos e cabeçalhos de assinatura para criar um webhook de serviço.
2. Valide se o notebook associado ao receptor do webhook do notebook é executado sempre que um evento de webhook de serviço específico é acionado.

Carga útil de webhooks de serviço

Quando um notebook é executado por meio de um webhook, as informações de carga útil do webhook são injetadas automaticamente no notebook em uma célula inicial. Após injetadas, as informações fornecidas na carga útil do webhook podem ser usadas no notebook para fluxos de trabalho de automação adicionais.

Carga útil de webhooks de serviço

O código a seguir é um exemplo de uma carga útil para um webhook de serviço de feição.

webhookPayload = {
    "serviceType": "FeatureServer",
    "changesUrl": "<change_url>",
    "name": "<webhook_name>",
    "id": "<webhook_id>",
    "folderName": "<folder_name>",
    "serviceName": "<service_name>",
    "events": [
        {
            "eventType": "FeaturesCreated",
            "when": 1740436800000
        },
        {
            "eventType": "FeaturesDeleted",
            "when": 1740436810000
        },
        {
            "eventType": "FeaturesUpdated",
            "when": 1740436820000
        }
    ]
}

Webhooks de serviço de geoprocessamento

O código a seguir é um exemplo de uma carga útil para um webhook de serviço de geoprocessamento.

webhookPayload = {
    "serviceType": "GPServer",
    "jobId": "<job_id>",
    "statusURL": "<status_url>",
    "name": "<webhook_name>",
    "taskName": "<task_name>",
    "folderName": "<folder_name>",
    "serviceName": "<service_name>",
    "events": [
        {
            "eventType": "esriJobSucceeded",
            "when": 1742337000000
        }
    ]
}