Automatizar flujos de trabajo con ArcGIS Notebooks

Servicios de Notebook le permite implementar varios métodos de automatización de flujos de trabajo, incluida la automatización a través de notebooks programados, webhooks y sus scripts personalizados con la API administrativa Ejecutar notebook.

Nota:

Para automatizar un notebook con tareas programadas, webhooks o la API Ejecutar notebook, el notebook debe usar un tiempo de ejecución de la versión 3.0 o posterior.

Programar tareas de notebook

Los autores de notebooks pueden programar ArcGIS Notebooks para su ejecución automática en un momento dado en el futuro, ya sea una vez o de forma recurrente. La creación de tareas para programar notebooks permite automatizar flujos de trabajo rutinarios, ejecutar procesos intensivos en datos fuera de las horas punta de uso y actualizar datasets regularmente. Por ejemplo, puede programar un notebook para hacer lo siguiente:

• Importar datos de una fuente en línea actualizada mensualmente, limpiar automáticamente los datos y aplicar las transformaciones necesarias y mover los datos a su espacio de trabajo.
• Ejecutar un flujo de trabajo de análisis de big data que requiera una gran potencia de procesamiento durante la noche, cuando los recursos de su equipo no se utilicen.
• Administrar los usuarios que hayan creado cuentas en su organización durante la semana anterior y enviarse la lista de los mismos en un correo electrónico.

Puede crear una o varias tareas para un notebook. De forma predeterminada, el autor o administrador del notebook puede crear un máximo de 20 tareas. Si se cambia la propiedad de un notebook, las tareas asociadas a ese notebook se desactivarán y se asignarán al nuevo propietario.

Las tareas programadas le permiten parametrizar notebooks. Cuando un notebook está parametrizado, le permite escribir código genérico que se puede adaptar a distintas entradas sin su interacción. Los parámetros elegidos se insertan en el notebook cuando se ejecuta una tarea y se pueden guardar opcionalmente en el notebook. Por ejemplo, un notebook parametrizado se puede usar para generar informes de contaminación del aire a nivel de región de forma recurrente. El notebook puede tener varias tareas programadas, una para cada región que se estudiará y, para cada tarea, se pueden introducir entradas parametrizadas en el notebook, como el nombre de la ciudad y el tipo de contaminación.

Nota:

Los administradores pueden ver los detalles, editar, pausar y reanudar, o eliminar cada tarea activa del cuaderno en el sitio desde la ventana Administrar tareas.

Puede configurar la tarea para guardar el estado del notebook en el elemento de notebook original una vez completada.

Se guardará una vista HTML estática del notebook para cada tarea programada que se ejecute.

Al utilizar la ventana Administrar tareas desde la página de inicio de los servicios de notebook, los administradores pueden ver detalles, editar, pausar y reanudar o eliminar cada tarea de notebook activa en el sitio. Los administradores y autores de notebooks con el privilegio programado del notebook pueden ver detalles, editar, pausar y reanudar, o eliminar una tarea del notebook en la página de detalles del notebook o en el panel de tareas del editor del notebook.

Si aún se está ejecutando una ejecución anterior de una tarea, se omitirá la ejecución de una nueva tarea programada. Por ejemplo, si una tarea está programada para ejecutarse cada 15 minutos, pero una instancia de esa tarea se ejecuta durante 20 minutos, se omitirá la siguiente ejecución programada. Si esto ocurre regularmente, el propietario de la tarea debe ajustar el intervalo de tiempo programado para que no se ejecute ninguna superposición entre ellas.

Para obtener más información sobre las tareas programadas de notebook, consulte el tema de ayuda Programar una tarea de notebook.

Límites de tareas programadas

Existen ciertos límites de usuario y organizativos relacionados con las tareas programadas del notebook.

Cambiar ejecuciones de notebook simultáneas automatizadas máximas (maxAutomatedNotebookJobsPerManager)

Cuando un notebook se ejecuta a través de una tarea programada, webhook o la API Ejecutar notebook, Servicios de notebook de automáticamente abre una nueva implementación de y ejecuta el notebook sin ninguna interacción de usuario. De forma predeterminada, Servicios de Notebook están configurados para ejecutar un máximo de 10 ejecuciones simultáneas de Notebook por cada implementación del servicio de automatización de notebook en los equipos de . Teniendo en cuenta los recursos disponibles en el clúster de Kubernetes, un administrador puede ajustar este límite modificando la propiedad de configuración maxAutomatedNotebookJobsPerManager de los Servicios de Notebook. Cualquier solicitud de notebook automatizada enviada después de exceder este límite se agregará a una cola y se ejecutará una vez que la cantidad de ejecuciones de tareas automatizadas caiga por debajo de este límite. Las tareas en cola fallarán si el tiempo de espera excede el tiempo de expiración.

Nota:

Esto no limita la cantidad de notebooks que se ejecutan de forma interactiva desde el editor de notebooks.

Puede cambiar el límite maxAutomatedNotebookJobsPerManager siguiendo los pasos siguientes.

Nota:

Aumentar el límite puede resultar en el uso de recursos adicionales en el equipo de nodos de .

1. Inicie sesión en su portal API de administrador de ArcGIS Enterprise como administrador.
2. Haga clic en Notebooks > Configuración > Actualizar configuración.
3. Haga clic en Ajustes > Sitio.
4. Cambie el valor de la propiedad maxAutomatedNotebookJobsPerManager.
5. Haga clic en Actualizar configuración de Notebook.

Máximo de tareas de notebook activas programadas por usuario

Cada autor de notebook con el privilegio para programar notebooks puede crear hasta un máximo de 20 tareas de notebook activas. Una vez alcanzado este límite, el usuario no puede crear nuevas tareas programadas. Se puede crear una nueva tarea una vez que una tarea existente cambia de Activa a Completada, Fallida o Inactiva. Este límite se puede cambiar actualizando la propiedad ExecuteNotebooksUserLimit mediante la operación Actualizar límites en la API de API de administrador de ArcGIS Enterprise.

Máximo de tareas de notebook activas programadas por organización

El número máximo de tareas de notebook activas programadas para una organización está limitado a 200. Este límite representa el número total de tareas activas que pueden ser propiedad de todos los usuarios de una organización. Una vez alcanzado este límite, los usuarios no pueden crear nuevas tareas de notebook programadas. Este límite se puede cambiar actualizando la operación ExecuteNotebooksOrgLimitActualizar límites en la API de API de administrador de ArcGIS Enterprise.

Número de resultados informados para una tarea programada

Los resultados de una tarea se informan y mantienen durante 30 ejecuciones. Cualquier tarea ejecutada antes de las 30 ejecuciones más recientes de una tarea se elimina de forma permanente. Este límite se puede cambiar actualizando la propiedad TaskRunHistoryCount mediante la operación Actualizar límites en la API de API de administrador de ArcGIS Enterprise.

Fallo automático de una tarea

Cualquier tarea que falle cinco veces consecutivas pasará automáticamente a un estado fallido y ya no se ejecutará. El propietario de la tarea debe asegurarse de que el notebook se puede ejecutar correctamente sin que intervenga el usuario antes de reactivar la tarea. Para garantizar que las tareas sigan ejecutándose, el propietario de la tarea debe identificar y rectificar el error y cambiar la tarea al estado Activo. Este límite se puede cambiar actualizando la propiedad FailedRunsDisableTask mediante la operación Actualizar límites en la API de API de administrador de ArcGIS Enterprise.

Automatizar un notebook con webhooks de la organización

Un webhook es un mecanismo que permite que una aplicación proporcione información basada en eventos a otras aplicaciones. Como administrador de ArcGIS Enterprise o como usuario con el privilegio de webhooks de organización, puede crear, administrar y configurar webhooks. Puede configurar los webhooks para que ejecuten automáticamente un notebook cuando sucedan eventos asociados con los elementos, grupos o usuarios. Servicios de Notebook actúa como el receptor de la carga del webhook. Una vez desencadenado un webhook, se realiza una solicitud HTTP a Servicios de Notebook para ejecutar un notebook elegido sin ninguna interacción del usuario.

Nota:

La propiedad del sistema maxExecuteNotebookContainersPerNode limita el número de ejecuciones concurrentes desde notebooks desde webhooks en Servicios de Notebook.

Crear un webhook

Los webhooks se pueden administrar desde la página Configuración de la organización. Siga estos pasos para crear un webhook:

1. Inicie sesión como administrador predeterminado o con un rol personalizado con el privilegio de webhooks de la organización.
2. Haga clic en Organización > Configuración > Webhooks.
3. Haga clic en Crear webhook.
4. Especifique un nombre de webhook.

   Por ejemplo, podría escribir Name=mynotebook_webhook.

5. Seleccione el tipo de evento que desencadenará el webhook.

   De forma predeterminada, se consideran todos los tipos de eventos (Elementos, Usuarios, Grupos y Roles).

6. Utilice Desencadenador para aceptar el valor predeterminado (/) o especifique uno o varios valores como eventos desencadenadores.

   Un ejemplo es Eventos=/elementos, /elementos/<itemId>,/usuarios.

   Consulte Eventos desencadenadores compatibles para obtener más información.

   Para ver ejemplos adicionales, consulte Eventos desencadenadores.

7. Seleccione Notebook como tipo de carga.
8. Seleccione el notebook que se ejecutará cuando se desencadene el webhook.
9. Si lo desea, introduzca una clave Secreto que se incluirá en la carga del webhook.

   También puede optar por usar valores generados de forma aleatoria para la clave Secreto.

10. Haga clic en Crear webhook para guardar la configuración del webhook y crear un webhook.

Administrar webhooks

Los webhooks se pueden administrar desde la página Configuración de la organización. Siga estos pasos para administrar los webhooks existentes:

1. Inicie sesión como administrador predeterminado o con un rol personalizado con el privilegio de webhooks de la organización.
2. Haga clic en Organización > Configuración > Webhooks para ver una lista de webhooks creados por usted y por otros administradores de webhooks.

Puede administrar sus webhooks existentes con las siguientes operaciones.

• Desactivar webhook: cuando un webhook esté en un estado activo, haga clic en Activo. Se le pedirá que confirme el cambio de estado. Haga clic en Confirmar para desactivar el webhook. La desactivación del webhook impide que se entreguen las cargas útiles cuando se desencadena el webhook.
• Activar webhook: cuando un webhook esté en un estado inactivo, haga clic en Inactivo. Se le pedirá que confirme el cambio de estado. Haga clic en Confirmar para activar el webhook. Una vez que se ha activado un webhook, reanudará la entrega de cargas.
• Editar webhook: haga clic en el botón de opciones del webhook y haga clic en Editar para actualizar los eventos desencadenadores de su webhook o el notebook especificado para el webhook.
• Eliminar webhook: haga clic en el botón de opciones del webhook y haga clic en Eliminar. Haga clic en Confirmar para eliminar el webhook.

Configuración de webhooks avanzada

Utilice Configuración de webhooks avanzada para cambiar propiedades como el número de intentos de entrega que se pueden realizar, notificaciones para el tiempo transcurrido y propiedades de tiempo de espera de notificación para webhooks. Esta configuración avanzada se aplicará a todos los webhooks de su organización. Para modificar la configuración de webhooks avanzada, siga estos pasos:

1. Inicie sesión como administrador predeterminado o con un rol personalizado con el privilegio de webhooks de la organización.
2. Haga clic en Organización > Configuración > Webhooks > Configuración de webhooks avanzada para modificar los valores predeterminados de las propiedades avanzadas del webhook.

Carga de webhooks de organización

Cuando se ejecuta un notebook desde un webhook, la información de carga del webhook se introduce automáticamente en el notebook en una celda inicial. Una vez introducida, la información proporcionada en la carga de webhooks se puede utilizar en el notebook para más flujos de trabajo de automatización.

Información de carga de webhooks incluida en un 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>",
        
        "webhookName": "<webhook_name>",
        "when": 1742596805000
    }
}

Automatizar un notebook con webhooks de servicio

Los webhooks, incluidos los de servicios de geoprocesamiento asíncronos, servicios de entidades y otros webhooks genéricos, pueden activar una ejecución de notebook en respuesta a eventos específicos Los administradores pueden registrar la URL de un receptor de webhook como URL de enlace o carga correspondiente a estos webhooks. Cuando se activa un evento específico asociado con un webhook, se llamará automáticamente a la URL del receptor de webhook del notebook, lo que inicia la ejecución del notebook correspondiente.

En las secciones siguientes se describe cómo configurar un receptor de webhook del notebook en Servicios de Notebook.

Crear una aplicación de claves de API

Las claves de API son tokens de larga duración que autorizan a un webhook de servicio a que ejecute un elemento de notebook asociado y acceda de forma segura a las capacidades y funcionalidades de ArcGIS Enterprise que se requieren para que se ejecute el notebook.

Las claves de API se generan utilizando credenciales de claves de API, un tipo de elemento alojado en la organización. Las credenciales de clave de API contienen ajustes que permiten generar claves de API y gestionar propiedades como sus privilegios y fecha de caducidad. El proceso de creación de credenciales de clave de API y el uso de claves de API en la aplicación se conoce como autenticación con clave de API.

Consulte los pasos para generar una clave de API en el tutorial Crear una clave de API. Conceda los privilegios Crear y editar notebooks, Crear, Actualizar y Eliminar elemento; si lo desea, conceda el privilegio Advanced notebook para ArcPy. Puede que se requieran privilegios adicionales en función de los flujos de trabajo realizados en el notebook.

Generar y copiar una clave de API

Para generar y copiar una clave API, siga estos pasos:

1. Inicie sesión como usuario administrativo.
2. Haga clic en la página Detalles de elemento del elemento de clave de API.
3. Realice los pasos de la sección Copiar la clave de API del tutorial Crear una clave de API.

Registrar un receptor de webhook de notebook

Para registrar un receptor de webhook de notebook, realice los pasos siguientes:

1. Inicie sesión en el directorio de Administrador de como administrador.

   La dirección URL es https://organization.domain.com/<context>/admin.

2. Haga clic en Notebooks > Webhook Receptores > Registrar receptor de webhook.

   La dirección URL es https://organization.domain.com/<context>/admin/notebooks/webhookReceivers/create.

3. Registre el receptor de webhook utilizando información en el tema Crear receptores de webhook en la API administrativa.

   Cuando se cree correctamente un receptor de webhook de un notebook, se devolverá la URL del receptor de webhook en la respuesta. Esta URL puede utilizarse como URL de enlace al registrar webhooks del servicio de geoprocesamiento asíncrono, webhooks del servicio de entidades y otros webhooks genéricos.

Crear un webhook de servicio de geoprocesamiento asíncrono o de servicio de entidades

Para crear un webhook de servicio de geoprocesamiento asíncrono o de servicio de entidades, realice los pasos siguientes:

1. Utilice la URL del receptor de webhook, encabezados secretos y encabezados de firma para crear un webhook de servicio.
2. Corrobore que el notebook asociado con el receptor de webhook del notebook se ejecuta cada vez que se activa un evento de webhook de servicio específico.

Carga de webhooks de servicio

Cuando se ejecuta un notebook desde un webhook, la información de carga del webhook se introduce automáticamente en el notebook en una celda inicial. Una vez introducida, la información proporcionada en la carga de webhooks se puede utilizar en el notebook para más flujos de trabajo de automatización.

Webhooks de servicio de entidades

El código siguiente es un ejemplo de carga de webhook de servicio de entidades.

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 servicio de geoprocesamiento

El código siguiente es un ejemplo de carga de webhook de servicio de geoprocesamiento.

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

Ejecutar la API del notebook

Los administradores y los creadores de notebooks también pueden automatizar un notebook para que se ejecute sin interacción del usuario con la operación Ejecutar notebook en el API de administrador de ArcGIS Enterprise. Esta operación ejecutará automáticamente un notebook cuando se invoque, pero si utiliza un script personalizado, puede programar que la ejecución automática se produzca a una hora determinada o en un horario regular. También puede utilizar un trabajo de cron o un programador de Windows para programar que la operación Ejecutar notebook se ejecute a una hora determinada o según un intervalo recurrente.

Para más información, consulte el tema de la operación Ejecutar notebook en la guía de referencia del Directorio de administrador.