O ArcGIS Notebook Server permite implementar vários métodos de automação do fluxo de trabalho, incluindo automação por meio de notebooks agendados, webhooks e seus próprios scripts personalizados usando a API administrativa de Executar Notebook.
Anotação:
Para automatizar um notebook usando tarefas agendadas, webhooks ou Executar API do Notebook, o notebook deve usar um tempo de execução da versão 3.0 ou posterior.
Agendar tarefas do notebook
Começando na versão 10.8.1, os autores do notebook podem agendar o ArcGIS Notebooks para execução automatizada em um horário fixo no futuro, uma vez ou de forma recorrente. A criação de tarefas para agendar notebooks permite automatizar fluxos de trabalho de rotina, executar processos com uso intensivo de dados durante o horário de menor uso e atualizar regularmente conjuntos de dados. Por exemplo, você pode programar um notebook para fazer o seguinte:
- Importar dados de uma fonte online que atualizam mensalmente, limpam automaticamente os dados e aplicam transformações necessárias e movem os dados para sua área de trabalho.
- Execute um fluxo de trabalho de análise do big data que exija alta capacidade de processamento durante a noite, quando os recursos da sua máquina estiverem sem uso.
- Gerencie usuários que criaram contas no seu portal durante a semana passada e envie a lista para você em um e-mail.
Você pode criar uma ou mais tarefas para um notebook. Por padrão, o autor ou administrador do notebook pode criar no máximo 20 tarefas. Se a propriedade do notebook for alterada, todas as tarefas associadas a este notebook serão desativadas e atribuídas ao novo proprietário.
Tarefas agendadas permitem parametrizar notebooks. Quando um notebook é parametrizado, ele permite escrever um código genérico que pode ser adaptado a várias entradas sem sua interação. Os parâmetros escolhidos são inseridos no notebook quando uma tarefa é executada e, opcionalmente, podem ser salvos no notebook. Por exemplo, um notebook parametrizado pode ser usado para gerar relatórios de poluição do ar em toda a região de forma recorrente. O notebook pode ter várias tarefas agendadas, uma para cada região a ser estudada, e para cada tarefa, entradas parametrizadas, como nome da cidade e tipo de poluição, podem ser inseridas no notebook.
Anotação:
O número de tarefas do notebook em execução simultânea é limitado pela propriedade do sistema maxExecuteNotebookContainersPerNode no Notebook Server.
Você pode configurar a tarefa para salvar o estado do notebook no item original do notebook após a conclusão.
Uma visualização de HTML estática do notebook será salva para cada tarefa agendada que é executada.
Usando a janela Gerenciar tarefas na página inicial do ArcGIS Notebook Server ou a página Tarefas no ArcGIS Notebook Server Manager, os administradores podem visualizar detalhes, editar, pausar e retomar ou excluir cada tarefa ativa do notebook no site. Os administradores e autores do notebook com o privilégio de agendar notebook podem visualizar detalhes, editar, pausar e retomar ou excluir uma tarefa do notebook na página de detalhes do notebook ou no painel de tarefas do editor de notebook.
Se uma execução anterior de uma tarefa ainda estiver em execução, uma nova execução de tarefa agendada será ignorada. Por exemplo, se uma tarefa for agendada para ser executada a cada 15 minutos, mas uma instância dessa tarefa for executada por 20 minutos, a próxima execução agendada será ignorada. Se isso ocorrer regularmente, o proprietário da tarefa deverá ajustar o intervalo de tempo agendado para que não haja sobreposição entre as execuções.
Para mais informações sobre as tarefas agendadas do notebook, consulte o tópico de ajuda Agendar uma tarefa do notebook.
Limites de tarefas agendadas
Há determinados limites de nível do usuário, organizacional e de site do ArcGIS Notebook Server (máquina) relacionados a tarefas agendadas do notebook.
Alterar o máximo de execuções simultâneas automatizadas do notebook (maxExecuteNotebookContainersPerNode)
Quando um notebook é executado por uma tarefa agendada, webhook ou Executar API do Notebook, o ArcGIS Notebook Server abre automaticamente um novo contêiner e executa o notebook sem nenhuma interação do usuário. Por padrão, ArcGIS Notebook Server está configurado para realizar no máximo 10 execuções simultâneas de notebook por cada máquina do Notebook Server. Considerando os recursos (CPU e RAM) disponíveis em cada máquina de site do Notebook Server, um administrador pode ajustar esse limite modificando a propriedade do sistema maxExecuteNotebookContainersPerNode no Notebook Server. Qualquer solicitação de notebook automatizado enviada após esse limite ser excedido será adicionada a uma fila e executada quando o número de execuções de tarefas automatizadas ficar abaixo desse limite. As tarefas enfileiradas falharão se o tempo de espera exceder o tempo limite.
Anotação:
Isso não limita o número de notebooks executados interativamente no editor de notebook.
Você pode alterar o limite de maxExecuteNotebookContainersPerNode seguindo as etapas abaixo.
Anotação:
Aumentar o limite pode resultar em recursos adicionais usados na máquina do Notebook Server.
- Entre no seu portal do ArcGIS Enterprise como um administrador.
- Abra o ArcGIS Notebook Server Manager.
- Clique em Configurações > Site
- Altere o valor da propriedade maxExecuteNotebookContainersPerNode .
- Clique em Salvar.
- Revise o aviso sobre a reinicialização do seu Notebook Server e clique em Salvar e Reiniciar para salvar as alterações.
Máximo de tarefas agendadas do notebook ativas por usuário
Cada autor de notebook com privilégio de agendar notebooks pode criar no máximo 20 tarefas ativas de notebook. Quando esse limite for atingido, o usuário não poderá criar novas tarefas agendadas. Uma nova tarefa pode ser criada quando uma tarefa existente muda de Ativa para Concluída, Com Falha ou Inativa. Este limite pode ser alterado atualizando a propriedade ExecuteNotebooksUserLimit utilizando a operação Atualizar Limites do Sistema no ArcGIS Portal Administrator API.
Máximo de tarefas agendadas do notebook ativas por organização
O máximo de tarefas agendadas do notebook ativas para uma organização é limitado a 200. Este limite representa o número total de tarefas ativas que podem ser de propriedade de todos os usuários de uma organização do Portal. Quando esse limite for atingido, os usuários não poderão criar novas tarefas de notebook agendadas. Este limite pode ser alterado atualizando a propriedade ExecuteNotebooksOrgLimit utilizando a operação Atualizar Limites do Sistema no ArcGIS Portal Administrator API.
Número de resultados relatados para uma tarefa agendada
Os resultados de uma tarefa são relatados e mantidos por 30 execuções. Qualquer tarefa executada antes das 30 execuções mais recentes de uma tarefa será excluída permanentemente. Este limite pode ser alterado atualizando a propriedade TaskRunHistoryCount utilizando a operação Atualizar Limites do Sistema no ArcGIS Portal Administrator API.
Falha automática de uma tarefa
Quaisquer tarefas que falharem cinco vezes consecutivas serão automaticamente alteradas para um estado de falha e não serão mais executadas. O proprietário da tarefa deve garantir que o notebook possa ser executado com sucesso sem qualquer interação do usuário antes de reativar a tarefa. Para garantir que as tarefas continuem em execução, o proprietário da tarefa deve identificar e corrigir a falha e alterar a tarefa para o estado Ativo. Este limite pode ser alterado atualizando a propriedade FailedRunsDisableTask utilizando a operação Atualizar Limites do Sistema no ArcGIS Portal Administrator API.
Automatize um notebook usando webhooks da organização
Um webhook é um mecanismo que permite que um aplicativo forneça a outros aplicativos informações sobre eventos. Como um administrador do ArcGIS EnterprisePortal ou um usuário com o privilégio webhooks da organização, você pode criar, gerenciar e configurar webhooks. Você poderá configurar webhooks para executar automaticamente um notebook de sua propriedade quando ocorrerem eventos associados aos itens, grupos ou usuários do portal. O Notebook Server atua como o receptor da carga útil do webhook. Após um webhook ser ativado, uma solicitação de HTTP será realizada no Notebook Server para executar um notebook escolhido sem nenhuma interação do usuário.
Anotação:
O número de tarefas do notebook em execução simultânea é limitado pela propriedade do sistema maxExecuteNotebookContainersPerNode no Notebook Server.
Criar um webhook
Os webhooks podem ser administrados na página de Configurações da organização do seu portal. Utilize as seguintes etapas para criar um webhook:
- Entre como administrador padrão ou papel personalizado com o privilégio de webhooks da organização.
- Navegue até Organização > Configurações > Webhooks.
- Clique em Criar webhook.
- Especifique um nome de webhook.
Por exemplo, você poderia digitar Name=mynotebook_webhook.
- 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.
- Use Ativador para aceitar o valor padrão (/) ou especificar um ou mais valores como eventos ativadores.
Um exemplo é Events=/items, /items/<itemId>,/users.
Consulte Eventos ativadores suportados para obter mais informações.
Para exemplos adicionais, consulte Eventos ativadores.
- 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. - Selecione o notebook que será executado quando o webhook for ativado.
- 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.
- Clique em Criar webhook para salvar as configurações do webhook e criar um webhook.
Gerenciar webhooks
Os webhooks podem ser administrados na página de Configurações da organização do seu portal. Use as seguintes etapas para gerenciar webhooks existentes:
- Entre como administrador padrão ou papel personalizado com o privilégio de webhooks da Organização.
- Navegue até Organização > Configurações > Webhooks para visualizar uma lista de webhooks criados por você e outros administradores de webhook.
Você pode gerenciar seus webhooks existentes com as seguintes operações.
- Desativar webhook—Quando um webhook estiver em um estado ativo, clique em Ativo. Você será solicitado a confirmar a alteração no status. Clique em Confirmar para desativar o webhook. 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. Você será solicitado a confirmar a alteração no status. Clique em Confirmar para ativar o webhook. 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 os eventos ativadores de webhook ou o notebook especificado para o webhook.
- Excluir webhook—Clique no botão de opções no webhook e clique emExcluir. Clique em Confirmar para excluir o webhook.
Configurações avançadas do webhook
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 do portal. Para modificar as configurações avançadas do webhook, conclua as seguintes etapas:
- Entre como administrador padrão ou papel personalizado com o privilégio de webhooks da Organização.
- Navegue até Organização > Configurações > Webhooks > configurações de webhook Avançadas para modificar os valores padrão das propriedades Avançadas do webhook.
Carga útil do webhook
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:
{
"properties": {
"itemId": "<itemId of the current notebook>"
},
"events": [
{
"source": "items",
"id": "<itemId of the item that resulted in webhook trigger>",
"userId": "<webhook user>",
"when": \<epoch time in ms when webhook was triggered\>,
"operation": "<type of operation that resulted in webhook trigger>",
"properties": {},
"username": "<webhook username>"
}
],
"info": {
"webhookId": "<webhookId>",
"portalURL": "<public portal url>",
"webhookName": "<webhook name>",
"when": \<epoch time in ms when webhook was triggered\>,
}
}Automatize um notebook usando webhooks de serviço
Introduzido como um recurso beta no ArcGIS Notebook Server 11.4, 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 no ArcGIS Notebook Server.
Criar uma aplicação de 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 de API são geradas usando credenciais de chave de API, um tipo de item hospedado em seu portal. 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.
Consulte o tutorial Criar uma chave de API para saber como gerar uma chave de API.
Anotação:
Antes de executar a etapa final de cópia do cache, siga as etapas nas seções abaixo para aplicar quaisquer privilégios adicionais necessários para executar o notebook.
Aplique privilégios ao seu aplicativo de chave de API
Para aplicar privilégios adicionais ao seu aplicativo de chave de API, conclua as seguintes etapas:
- Entre no diretório Portal usando as credenciais de usuário administrativo que foram usadas para criar a chave de API.
A URL do diretório Portal é https://portal.domain.com/webadaptorname/sharing/rest.
Após efetuar login, você será direcionado para a página de Recursos do usuário para o usuário conectado.
A URL da página Recurso do usuário é https://portal.domain.com/webadaptorname/sharing/rest/community/users/<username>
- Clique em Conteúdo do Usuário.
- Clique no link do item correspondente à sua chave de API recém-criada.
A página da API de detalhes do item para a chave da API é aberta: https://portal.domain.com/webadaptorname/sharing/rest/community/users/<username>/items/<itemId>
- Clique em Atualizar Aplicativo
- Adicione os seguintes privilégios na seção Privilégios.
- Conceder permissão para executar um notebook: "premium:publisher:createNotebooks"
- Opcionalmente, permita a importação e o uso de ArcPy no notebook associado: "premium:publisher:createAdvancedNotebooks"
- Inclua quaisquer outros privilégios necessários para que o código do seu notebook seja executado com sucesso.
O exemplo de chave de API a seguir tem o privilégio de acessar o item do notebook referenciado por seu itemId, privilégios para notebooks padrão e avançados e privilégios para publicar camadas de feições.
[ "portal:app:access:item:bfebec55911a4cd2a85ff9eae51dcf68", "premium:publisher:createAdvancedNotebooks", "premium:publisher:createNotebooks", "portal:user:createItem", "portal:publisher:publishFeatures" ] - Clique em Atualizar Aplicativo para salvar suas alterações.
- Saia do diretório Portal.
Gerar e copiar uma chave de API
Siga as etapas abaixo para gerar e copiar uma chave de API:
- Entre no seu portal como usuário administrativo.
- Clique na página Detalhes do item da chave de API.
- Siga as etapas na seção Copiar a chave de API do tutorial Criar uma chave de API.
Registre um receptor de webhook de notebook
Para registrar um receptor webhook de notebook, conclua as seguintes etapas:
- Entre no diretório do ArcGIS Notebook Server administrador usando as credenciais de usuário administrativo do portal.
A URL é https://notebookserverwebadaptor.domain.com/webadaptor/admin.
- Clique em Notebooks > Receptores de Webhook > Registrar Receptor Webhook.
A URL é https://notebookserverwebadaptor.domain.com/webadaptor/admin/notebooks/webhookReceivers/create.
- Registre o receptor de webhook usando as informações no tópico Criar Receptores de Webhook na API administrativa.
Após a criação bem-sucedida de um receptor de webhook de notebook, uma URL do receptor de webhook será retornada na resposta. Esta URL pode ser usada como URL de hook ao registrar webhooks de serviços de geoprocessamento assíncronos, webhooks de serviços de feições e outros webhooks genéricos.
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:
- Use a URL do receptor do webhook, cabeçalhos secretos e cabeçalhos de assinatura para criar um webhook de serviço assíncrono.
- Valide se o notebook associado ao receptor do webhook do notebook é executado sempre que um evento de webhook de serviço específico é acionado.
Executar API do Notebook
Os administradores e autores do notebook também podem automatizar um notebook para ser executado sem interação do usuário, usando a operação Executar Notebook no ArcGIS Notebook Server Administrator Directory. Essa operação executará automaticamente um notebook quando solicitada, mas usando seu próprio script personalizado, você pode agendá-la para ser executada automaticamente em um horário definido ou em um agendamento regular. Um trabalho cron ou agendador do Windows também pode ser usado para agendar a operação Executar Notebook para ser executada em um horário definido ou em um intervalo recorrente.
Para saber mais, consulte o tópico Executar Notebook no guia de referência do Diretório do Administrador.