Compartir vía

Creación de un desencadenador que ejecuta una canalización en una programación

  • Artículo

SE APLICA A: Azure Data Factory Azure Synapse Analytics

Sugerencia

Pruebe Data Factory en Microsoft Fabric, una solución de análisis todo en uno para empresas. Microsoft Fabric abarca todo, desde el movimiento de datos hasta la ciencia de datos, el análisis en tiempo real, la inteligencia empresarial y los informes. Obtenga información sobre cómo iniciar una nueva evaluación gratuita.

En este artículo se proporciona información sobre el desencadenador de programación y los pasos para crear, iniciar y supervisar un desencadenador de programación. Para otros tipos de desencadenadores, consulte Ejecución y desencadenadores de canalización.

Al crear un desencadenador programado, se especifica una programación, como una fecha de inicio, una recurrencia o una fecha de finalización para el desencadenador, y se asocia a una canalización. Las canalizaciones y los desencadenadores tienen una relación de varios a varios. Varios desencadenadores pueden comenzar una única canalización. Un único desencadenador puede iniciar varias canalizaciones.

En las secciones siguientes se proporcionan los pasos necesarios para crear un desencadenador de programación de diferentes maneras.

Experiencia del portal de Azure Data Factory y Azure Synapse

Puede crear un desencadenador de programación para programar una canalización que se ejecute periódicamente, como cada hora o diariamente.

Nota:

Para ver un tutorial completo sobre cómo crear una canalización y un desencadenador de programación, que asocia el desencadenador a la canalización y ejecuta y supervisa la canalización, consulte Inicio rápido: Creación de una factoría de datos mediante la interfaz de usuario de Data Factory.

  1. Cambie a la pestaña Editar de Data Factory o a la pestaña Integrar de Azure Synapse.

  1. Seleccione Trigger (Desencadenador) en el menú y, después, seleccione New/Edit (Nuevo/Editar).

    Captura de pantalla que muestra el menú Nuevo desencadenador.

  2. En la página Agregar desencadenadores, seleccione Elegir desencadenador y luego seleccione Nuevo.

    Captura de pantalla que muestra el panel Agregar desencadenadores.

  3. En la página Nuevo desencadenador:

    1. Asegúrese de que Programación está seleccionado para Tipo.

    2. Especifique la fecha y hora de inicio del desencadenador para Fecha de inicio. De forma predeterminada, se establece la fecha y hora actuales en la hora universal coordinada (UTC).

    3. Especifique la zona horaria en la que se crea el desencadenador. La configuración de zona horaria se aplica a Fecha de inicio, Fecha de finalización y Programación de tiempos de ejecución en Opciones de periodicidad avanzadas. Cambiar la configuración de la zona horaria no cambia automáticamente la fecha de inicio. Asegúrese de que la fecha de inicio es correcta en la zona horaria especificada. La hora de ejecución programada del desencadenador se considera posterior a la fecha de inicio. (Asegúrese de que la fecha de inicio sea al menos de 1 minuto que el tiempo de ejecución o de lo contrario desencadena la canalización en la siguiente periodicidad).

      Nota:

      En el caso de las zonas horarias que observan el horario de verano, el tiempo de desencadenador se ajusta automáticamente para el cambio de dos veces al año, si la periodicidad se establece en Días o superior. Para no participar en el cambio de horario de verano, seleccione una zona horaria que no observe el horario de verano, por ejemplo, UTC.

      El ajuste del horario de verano solo se produce para un desencadenador con la periodicidad establecida en Días o superior. Si el desencadenador se establece en la frecuencia Horas o Minutos, sigue activándose a intervalos regulares.

    4. Especifique Periodicidad para el desencadenador. Seleccione uno de los valores de la lista desplegable (Cada minuto, Cada hora, Diaria, Semanalo Mensual). Introduzca el multiplicador en el cuadro de texto. Por ejemplo, si desea que el desencadenador se ejecute una vez cada 15 minutos, seleccione Cada minuto y escriba 15 en el cuadro de texto.

    5. En Periodicidad, si selecciona Día(s), Semana(s) o Mes(es) en la lista desplegable, podrá ver las Opciones de periodicidad avanzadas.

      Captura de pantalla que muestra las opciones avanzadas de periodicidad de los días, las semanas y los meses.

    6. Para especificar una hora de finalización, seleccione Especificar una fecha de finalización. Especifique la información de Finaliza en y luego seleccione Aceptar.

      Un costo está asociado a cada ejecución de canalización. Si está probando, es posible que quiera asegurarse de que la canalización se desencadene solo un par de veces. No obstante, asegúrese de que hay tiempo suficiente para que la canalización se ejecute entre la hora de publicación y la hora de finalización. El desencadenador se aplica después de publicar la solución, no cuando se guarda en la interfaz de usuario.

      Captura de pantalla que muestra la configuración del desencadenador.

      Captura de pantalla que muestra la configuración del desencadenador para la fecha y hora de finalización.

  4. En la ventana Nuevo desencadenador, seleccione Sí en la opción Activada y luego seleccione Aceptar. Puede utilizar esta casilla para desactivar el desencadenador más adelante.

    Captura de pantalla que muestra la opción Activado.

  5. En la ventana Nuevo desencadenador, revise el mensaje de advertencia y seleccione Aceptar.

    Captura de pantalla que muestra cómo seleccionar el botón Aceptar.

  6. Seleccione Publicar todo para publicar los cambios. El desencadenador no inicia las ejecuciones de canalización hasta que se publican los cambios.

    Captura de pantalla que muestra el botón Publicar todo.

  7. Cambie a la pestaña Ejecuciones de canalización de la izquierda y seleccione Actualizar para actualizar la lista. Verá que el desencadenador programado ejecuta las ejecuciones de la canalización. Observe los valores de la columna Triggered By (Desencadenado por). Si usa la opción Desencadenar ahora, verá que el desencadenador manual se ejecuta en la lista.

  1. Cambie a la vista Ejecuciones de desencadenador>Programación.

Azure PowerShell

Nota:

Se recomienda usar el módulo Azure Az de PowerShell para interactuar con Azure. Para comenzar, consulte Instalación de Azure PowerShell. Para más información sobre cómo migrar al módulo Az de PowerShell, consulte Migración de Azure PowerShell de AzureRM a Az.

En esta sección se muestra cómo usar Azure PowerShell para crear, iniciar y supervisar un desencadenador de la programación. Para ver que este ejemplo funciona, consulte primero Inicio rápido: crear una factoría de datos mediante Azure PowerShell. A continuación, agregue el código siguiente al método principal, de modo que se crea e inicia un desencadenador de programación que se ejecuta cada 15 minutos. El desencadenador está asociado a una canalización denominada Adfv2QuickStartPipeline que se crea como parte del inicio rápido.

Requisitos previos

Código de ejemplo

  1. Cree un archivo JSON llamado MyTrigger.json en la carpeta *C:\ADFv2QuickStartPSH* con el siguiente contenido:

    Importante

    Antes de guardar el archivo JSON, establezca el valor del elemento startTime en la hora UTC actual. Establezca el valor del elemento endTime en una hora más allá de la hora UTC actual.

    {
    "properties": {
        "name": "MyTrigger",
        "type": "ScheduleTrigger",
        "typeProperties": {
            "recurrence": {
                "frequency": "Minute",
                "interval": 15,
                "startTime": "2017-12-08T00:00:00Z",
                "endTime": "2017-12-08T01:00:00Z",
                "timeZone": "UTC"
            }
        },
        "pipelines": [{
                "pipelineReference": {
                    "type": "PipelineReference",
                    "referenceName": "Adfv2QuickStartPipeline"
                },
                "parameters": {
                    "inputPath": "adftutorial/input",
                    "outputPath": "adftutorial/output"
                }
            }
        ]
    }
}

    En el fragmento de código de JSON:

    • El elemento type del desencadenador se establece en ScheduleTrigger.

    • El elemento frequency se establece en Minute y el elemento interval se establece en 15. Por lo tanto, el desencadenador ejecuta la canalización cada 15 minutos entre las horas de inicio y finalización.

    • El elemento timeZone especifica la zona horaria en la que se crea el desencadenador. Esta configuración afecta tanto a startTime como a endTime.

    • El elemento endTime es una hora después del valor del elemento startTime. Por lo tanto, el desencadenador ejecuta la canalización 15 minutos, 30 minutos y 45 minutos después de la hora de inicio. No olvide actualizar la hora de inicio a la hora UTC actual y la hora de finalización a una hora más allá de la hora de inicio.

      Importante

      Para la zona horaria UTC, startTime y endTime deben seguir el formato yyyy-MM-ddTHH:mm:ssZ. Para otras zonas horarias, startTime y endTime siguen el formato yyyy-MM-ddTHH:mm:ss.

      Según el estándar ISO 8601, el sufijo Z se usa para marcar la marca de tiempo de la fecha y hora a la zona horaria UTC y hacer que el campo timeZone sea inútil. Si falta el sufijo Z para la zona horaria UTC, el resultado es un error al desencadenar activación.

    • El desencadenador está asociado a la canalización de Adfv2QuickStartPipeline. Para asociar varias canalizaciones a un desencadenador, agregue más secciones pipelineReference.

    • La canalización del inicio rápido toma dos valores de parameters: inputPath y outputPath. Estos parámetros se pasan desde el desencadenador.

  2. Cree un desencadenador mediante el cmdlet Set-AzDataFactoryV2Trigger:

    Set-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger" -DefinitionFile "C:\ADFv2QuickStartPSH\MyTrigger.json"

  3. Confirme que el estado del desencadenador es Detenido mediante el cmdlet Get-AzDataFactoryV2Trigger:

    Get-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger"

  4. Inicie el desencadenador mediante el cmdlet Start-AzDataFactoryV2Trigger:

    Start-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger"

  5. Confirme que el estado del desencadenador es Iniciado mediante el cmdlet Get-AzDataFactoryV2Trigger:

    Get-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger"

  6. Haga que el desencadenador se ejecute en Azure PowerShell mediante el cmdlet Get-AzDataFactoryV2TriggerRun. Para obtener información acerca de cómo se ejecuta el desencadenador, ejecute el siguiente comando periódicamente. Actualice los valores de TriggerRunStartedAfter y TriggerRunStartedBefore para que coincidan con los valores de la definición del desencadenador:

    Get-AzDataFactoryV2TriggerRun -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -TriggerName "MyTrigger" -TriggerRunStartedAfter "2017-12-08T00:00:00" -TriggerRunStartedBefore "2017-12-08T01:00:00"

    Nota:

    La hora de desencadenado de los desencadenadores programados se especifica en la marca de tiempo UTC. TriggerRunStartedAfter y TriggerRunStartedBefore también esperan la marca de tiempo UTC.

    Para supervisar las ejecuciones del desencadenador y de la canalización en Azure Portal, consulte la sección acerca de la supervisión de ejecuciones de canalización.

CLI de Azure

En esta sección se muestra cómo usar la CLI de Azure para crear, iniciar y supervisar un desencadenador programado. Para ver que este ejemplo funciona, consulte primero Inicio rápido: crear un Azure Data Factory mediante la CLI de Azure. A continuación, siga los pasos para crear e iniciar un desencadenador programado que se ejecute cada 15 minutos. El desencadenador está asociado a una canalización denominada Adfv2QuickStartPipeline que se crea como parte del inicio rápido.

Requisitos previos

Código de ejemplo

  1. En su directorio de trabajo, cree un archivo JSON llamado MyTrigger.json con las propiedades del desencadenador. En este ejemplo, use el siguiente contenido:

    Importante

    Antes de guardar el archivo JSON, establezca el valor del elemento startTime en la hora UTC actual. Establezca el valor del elemento endTime en una hora más allá de la hora UTC actual.

    {
    "name": "MyTrigger",
    "type": "ScheduleTrigger",
    "typeProperties": {
        "recurrence": {
            "frequency": "Minute",
            "interval": 15,
            "startTime": "2017-12-08T00:00:00Z",
            "endTime": "2017-12-08T01:00:00Z",
            "timeZone": "UTC"
        }
    },
    "pipelines": [{
            "pipelineReference": {
                "type": "PipelineReference",
                "referenceName": "Adfv2QuickStartPipeline"
            },
            "parameters": {
                "inputPath": "adftutorial/input",
                "outputPath": "adftutorial/output"
            }
        }
    ]
}

    En el fragmento de código de JSON:

    • El elemento type del desencadenador se establece en ScheduleTrigger.

    • El elemento frequency se establece en Minute y el elemento interval se establece en 15. Por lo tanto, el desencadenador ejecuta la canalización cada 15 minutos entre las horas de inicio y finalización.

    • El elemento timeZone especifica la zona horaria en la que se crea el desencadenador. Esta configuración afecta tanto a startTime como a endTime.

    • El elemento endTime es una hora después del valor del elemento startTime. Por lo tanto, el desencadenador ejecuta la canalización 15 minutos, 30 minutos y 45 minutos después de la hora de inicio. No olvide actualizar la hora de inicio a la hora UTC actual y la hora de finalización a una hora más allá de la hora de inicio.

      Importante

      Para la zona horaria UTC, el startTime y endTime deben seguir el formato yyyy-MM-ddTHH:mm:ssZ. Para otras zonas horarias, startTime y endTime siguen el formato yyyy-MM-ddTHH:mm:ss.

      Según el estándar ISO 8601, el sufijo Z se usa para marcar la marca de tiempo de la fecha y hora a la zona horaria UTC y representar el campo timeZone inútil. Si falta el sufijo de Z para la zona horaria UTC, el resultado es un error al desencadenar activación.

    • El desencadenador está asociado a la canalización de Adfv2QuickStartPipeline. Para asociar varias canalizaciones a un desencadenador, agregue más secciones pipelineReference.

    • La canalización del inicio rápido toma dos valores de parameters: inputPath y outputPath. Estos parámetros se pasan desde el desencadenador.

  2. Cree un desencadenador utilizando el comando az datafactory trigger create:

    az datafactory trigger create --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory"  --name "MyTrigger" --properties @MyTrigger.json

  3. Confirme que el estado del desencadenador es Detenido utilizando el comando az datafactory trigger show:

    az datafactory trigger show --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --name "MyTrigger"

  4. Inicie el desencadenador utilizando el comando az datafactory trigger start:

    az datafactory trigger start --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --name "MyTrigger"

  5. Confirme que el estado del desencadenador es Iniciado utilizando el comando az datafactory trigger show:

    az datafactory trigger show --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --name "MyTrigger"

  6. Obtenga las ejecuciones del desencadenador en la CLI de Azure mediante el comando az datafactory trigger-run query-by-factory. Para obtener información sobre cómo se ejecuta el desencadenador, ejecute el siguiente comando periódicamente. Actualice los valores de last-updated-after y last-updated-before para que coincidan con los valores de la definición del desencadenador:

    az datafactory trigger-run query-by-factory --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --filters operand="TriggerName" operator="Equals" values="MyTrigger" --last-updated-after "2017-12-08T00:00:00" --last-updated-before "2017-12-08T01:00:00"

    Nota:

    Las horas de desencadenador de los desencadenadores programados se especifican en la marca de tiempo UTC. last-updated-after y last-updated-before también esperan una marca de tiempo UTC.

    Para supervisar las ejecuciones del desencadenador y de la canalización en Azure Portal, consulte la sección acerca de la supervisión de ejecuciones de canalización.

.NET SDK

En esta sección se muestra cómo usar el SDK de.NET para crear, iniciar y supervisar un desencadenador. Para ver que este ejemplo funciona, consulte primero Inicio rápido: Creación crear una factoría de datos mediante el SDK de .NET. A continuación, agregue el código siguiente al método principal, de modo que se crea e inicia un desencadenador de programación que se ejecuta cada 15 minutos. El desencadenador está asociado a una canalización denominada Adfv2QuickStartPipeline que se crea como parte del inicio rápido.

Para crear e iniciar un desencadenador de programación que se ejecuta cada 15 minutos, agregue el código siguiente al método principal:

            // Create the trigger
            Console.WriteLine("Creating the trigger");

            // Set the start time to the current UTC time
            DateTime startTime = DateTime.UtcNow;

            // Specify values for the inputPath and outputPath parameters
            Dictionary<string, object> pipelineParameters = new Dictionary<string, object>();
            pipelineParameters.Add("inputPath", "adftutorial/input");
            pipelineParameters.Add("outputPath", "adftutorial/output");

            // Create a schedule trigger
            string triggerName = "MyTrigger";
            ScheduleTrigger myTrigger = new ScheduleTrigger()
            {
                Pipelines = new List<TriggerPipelineReference>()
                {
                    // Associate the Adfv2QuickStartPipeline pipeline with the trigger
                    new TriggerPipelineReference()
                    {
                        PipelineReference = new PipelineReference(pipelineName),
                        Parameters = pipelineParameters,
                    }
                },
                Recurrence = new ScheduleTriggerRecurrence()
                {
                    // Set the start time to the current UTC time and the end time to one hour after the start time
                    StartTime = startTime,
                    TimeZone = "UTC",
                    EndTime = startTime.AddHours(1),
                    Frequency = RecurrenceFrequency.Minute,
                    Interval = 15,
                }
            };

            // Now, create the trigger by invoking the CreateOrUpdate method
            TriggerResource triggerResource = new TriggerResource()
            {
                Properties = myTrigger
            };
            client.Triggers.CreateOrUpdate(resourceGroup, dataFactoryName, triggerName, triggerResource);

            // Start the trigger
            Console.WriteLine("Starting the trigger");
            client.Triggers.Start(resourceGroup, dataFactoryName, triggerName);

Para crear desencadenadores en una zona horaria diferente, aparte de UTC, se requiere la siguiente configuración:

<<ClientInstance>>.SerializationSettings.DateFormatHandling = Newtonsoft.Json.DateFormatHandling.IsoDateFormat;
<<ClientInstance>>.SerializationSettings.DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Unspecified;
<<ClientInstance>>.SerializationSettings.DateParseHandling = DateParseHandling.None;
<<ClientInstance>>.DeserializationSettings.DateParseHandling = DateParseHandling.None;
<<ClientInstance>>.DeserializationSettings.DateFormatHandling = Newtonsoft.Json.DateFormatHandling.IsoDateFormat;
<<ClientInstance>>.DeserializationSettings.DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Unspecified;

Para supervisar una ejecución de desencadenador, agregue el código siguiente a la última instrucción Console.WriteLine del ejemplo:

            // Check that the trigger runs every 15 minutes
            Console.WriteLine("Trigger runs. You see the output every 15 minutes");

            for (int i = 0; i < 3; i++)
            {
                System.Threading.Thread.Sleep(TimeSpan.FromMinutes(15));
                List<TriggerRun> triggerRuns = client.Triggers.ListRuns(resourceGroup, dataFactoryName, triggerName, DateTime.UtcNow.AddMinutes(-15 * (i + 1)), DateTime.UtcNow.AddMinutes(2)).ToList();
                Console.WriteLine("{0} trigger runs found", triggerRuns.Count);

                foreach (TriggerRun run in triggerRuns)
                {
                    foreach (KeyValuePair<string, string> triggeredPipeline in run.TriggeredPipelines)
                    {
                        PipelineRun triggeredPipelineRun = client.PipelineRuns.Get(resourceGroup, dataFactoryName, triggeredPipeline.Value);
                        Console.WriteLine("Pipeline run ID: {0}, Status: {1}", triggeredPipelineRun.RunId, triggeredPipelineRun.Status);
                        List<ActivityRun> runs = client.ActivityRuns.ListByPipelineRun(resourceGroup, dataFactoryName, triggeredPipelineRun.RunId, run.TriggerRunTimestamp.Value, run.TriggerRunTimestamp.Value.AddMinutes(20)).ToList();
                    }
                }
            }

Para supervisar las ejecuciones del desencadenador y de la canalización en Azure Portal, consulte la sección acerca de la supervisión de ejecuciones de canalización.

SDK de Python

En esta sección se muestra cómo usar el SDK de Python para crear, iniciar y supervisar un desencadenador. Para ver este ejemplo en funcionamiento, consulte primero Inicio rápido: crear una factoría de datos mediante el SDK de Python. A continuación, agregue el siguiente bloque de código después del bloque de código monitor the pipeline run en el script de Python. Este código crea un desencadenador de programación que se ejecuta cada 15 minutos entre las horas de inicio y finalización especificadas. Actualice la variable start_time a la hora UTC actual y la variable end_time a una hora más allá de la hora UTC actual.

    # Create a trigger
    tr_name = 'mytrigger'
    scheduler_recurrence = ScheduleTriggerRecurrence(frequency='Minute', interval='15',start_time='2017-12-12T04:00:00Z', end_time='2017-12-12T05:00:00Z', time_zone='UTC')
    pipeline_parameters = {'inputPath':'adftutorial/input', 'outputPath':'adftutorial/output'}
    pipelines_to_run = []
    pipeline_reference = PipelineReference('copyPipeline')
    pipelines_to_run.append(TriggerPipelineReference(pipeline_reference, pipeline_parameters))
    tr_properties = TriggerResource(properties=ScheduleTrigger(description='My scheduler trigger', pipelines = pipelines_to_run, recurrence=scheduler_recurrence))
    adf_client.triggers.create_or_update(rg_name, df_name, tr_name, tr_properties)

    # Start the trigger
    adf_client.triggers.start(rg_name, df_name, tr_name)

Para supervisar las ejecuciones del desencadenador y de la canalización en Azure Portal, consulte la sección acerca de la supervisión de ejecuciones de canalización.

Plantilla del Administrador de recursos de Azure

Puede usar una plantilla de Azure Resource Manager para crear un desencadenador. Para obtener instrucciones paso a paso, consulte Crear una factoría de datos de Azure mediante una plantilla de Azure Resource Manager.

Transmisión de la hora de inicio del desencadenador a una canalización

La versión 1 de Azure Data Factory admite la lectura o escritura de datos con particiones mediante las variables del sistema SliceStart, SliceEnd, WindowStarty WindowEnd. En la versión actual de las canalizaciones de Data Factory y Azure Synapse, puede lograr este comportamiento mediante un parámetro de canalización. La hora de inicio y la hora programada para el desencadenador se establecen como el valor del parámetro de la canalización. En el ejemplo siguiente, la hora programada para el desencadenador se pasa como un valor al parámetro de canalización scheduledRunTime:

"parameters": {
    "scheduledRunTime": "@trigger().scheduledTime"
}

Esquema JSON

La siguiente definición de JSON le muestra cómo crear un desencadenador de programación con la programación y periodicidad:

{
  "properties": {
    "type": "ScheduleTrigger",
    "typeProperties": {
      "recurrence": {
        "frequency": <<Minute, Hour, Day, Week, Month>>,
        "interval": <<int>>,             // Optional, specifies how often to fire (default to 1)
        "startTime": <<datetime>>,
        "endTime": <<datetime - optional>>,
        "timeZone": "UTC"
        "schedule": {                    // Optional (advanced scheduling specifics)
          "hours": [<<0-23>>],
          "weekDays": [<<Monday-Sunday>>],
          "minutes": [<<0-59>>],
          "monthDays": [<<1-31>>],
          "monthlyOccurrences": [
               {
                    "day": <<Monday-Sunday>>,
                    "occurrence": <<1-5>>
               }
           ]
        }
      }
    },
   "pipelines": [
            {
                "pipelineReference": {
                    "type": "PipelineReference",
                    "referenceName": "<Name of your pipeline>"
                },
                "parameters": {
                    "<parameter 1 Name>": {
                        "type": "Expression",
                        "value": "<parameter 1 Value>"
                    },
                    "<parameter 2 Name>" : "<parameter 2 Value>"
                }
           }
      ]
  }
}

Importante

La propiedad parameters es una propiedad obligatoria del elemento pipelines. Si la canalización no toma ningún parámetro, debe incluir una definición JSON vacía para la propiedad parameters.

Información general del esquema

En la tabla siguiente se proporciona información general de alto nivel de los elementos de esquema principales relacionados con la periodicidad y la programación de un desencadenador.

Propiedad JSON Descripción
startTime Valor de fecha y hora. Para programaciones sencillas, el valor de la propiedad startTime se aplica a la primera aparición. En el caso de programaciones complejas, el desencadenador no se inicia antes del valor startTime especificado.
Para la zona horaria UTC, el formato es 'yyyy-MM-ddTHH:mm:ssZ'. Para otras zonas horarias, el formato es yyyy-MM-ddTHH:mm:ss.
endTime Fecha y hora de finalización para el desencadenador. El desencadenador no se ejecuta después de la fecha y hora de finalización especificadas. El valor de la propiedad no puede estar en el pasado. Esta propiedad es opcional.
Para la zona horaria UTC, el formato es 'yyyy-MM-ddTHH:mm:ssZ'. Para otras zonas horarias, el formato es yyyy-MM-ddTHH:mm:ss.
timeZone Zona horaria en la que se crea el desencadenador. Esta configuración afecta a startTime, endTime y schedule. Consulte una lista de zonas horarias admitidas.
recurrence Objeto que especifica las reglas de periodicidad para el desencadenador. El objeto recurrence admite los elementos frequency, interval, endTime, count y schedule. Cuando se define un objeto de periodicidad, se requiere el elemento frequency. Los demás elementos del objeto recurrence son opcionales.
frequency Unidad de frecuencia a la que se repite el desencadenador. Los valores admitidos incluyen minute, hour, day, week, y month.
interval Entero positivo que denota el intervalo del valor frequency, que determina la frecuencia con la que se ejecuta el desencadenador. Por ejemplo, si el interval es 3 y el frequency es week, el desencadenador se repite cada 3 semanas.
schedule La programación de periodicidad para el desencadenador. Un desencadenador con un valor frequency especificado modifica su periodicidad en función de una programación de periodicidad. La propiedad schedule contiene modificaciones para la periodicidad que se basan en minutos, horas, días laborables, días de mes y número de semana.

Importante

Para la zona horaria UTC, startTime y endTime deben seguir el formato yyyy-MM-ddTHH:mm:ssZ. Para otras zonas horarias, startTime y endTime siguen el formato yyyy-MM-ddTHH:mm:ss.

Según el estándar ISO 8601, el sufijo Z se usa para marcar la marca de tiempo de la fecha y hora a la zona horaria UTC y representar el campo timeZone inútil. Si falta el sufijo de Z para la zona horaria UTC, el resultado es un error al desencadenar activación.

Valores predeterminados del esquema, límites y ejemplos

Propiedad JSON Tipo Obligatorio Valor predeterminado Valores válidos Ejemplo
startTime Cadena Sí None Fechas-horas ISO-8601 Para la zona horaria UTC: "startTime" : "2013-01-09T09:30:00-08:00Z"
Para otras zonas horarias: "2013-01-09T09:30:00-08:00"
timeZone Cadena Sí None Valores de zona horaria "UTC"
recurrence Object Sí None Objeto de periodicidad "recurrence" : { "frequency" : "monthly", "interval" : 1 }
interval Number No 1 De 1 a 1000 "interval":10
endTime Cadena Sí None Valor de fecha y hora que representa una hora en el futuro Para la zona horaria UTC: "endTime" : "2013-02-09T09:30:00-08:00Z"
Para otras zonas horarias: "endTime" : "2013-02-09T09:30:00-08:00"
schedule Object No None Objeto de programación "schedule" : { "minute" : [30], "hour" : [8,17] }

Opción de zona horaria

Estas son algunas de las zonas horarias compatibles con los desencadenadores programados.

Zona horaria Diferencia horaria con UTC (sin horario de verano) valor timeZone Observar el horario de verano Formato de marca de tiempo
Hora universal coordinada 0 UTC No 'yyyy-MM-ddTHH:mm:ssZ'
Hora del Pacífico (PT) -8 Pacific Standard Time Sí 'yyyy-MM-ddTHH:mm:ss'
Hora central (CT) -6 Central Standard Time Sí 'yyyy-MM-ddTHH:mm:ss'
Hora oriental (ET) -5 Eastern Standard Time Sí 'yyyy-MM-ddTHH:mm:ss'
Hora del meridiano de Greenwich (GMT) 0 GMT Standard Time Sí 'yyyy-MM-ddTHH:mm:ss'
Hora estándar centroeuropea +1 W. Europe Standard Time Sí 'yyyy-MM-ddTHH:mm:ss'
Hora estándar de la India (IST) +5:30 India Standard Time No 'yyyy-MM-ddTHH:mm:ss'
Hora estándar de China +8 China Standard Time No 'yyyy-MM-ddTHH:mm:ss'

Esta lista está incompleta. Para obtener una lista completa de las opciones de zona horaria, consulte la página Crear desencadenadores en el portal.

Propiedad startTime

En la tabla siguiente se muestra cómo la propiedad startTime controla una ejecución de desencadenador.

Valor de startTime Periodicidad sin programación Periodicidad con programación
Hora de inicio en el pasado Calcula la primera hora de ejecución futura después de la hora de inicio y se ejecuta a esa hora.

Realiza ejecuciones posteriores según el cálculo desde la última hora de ejecución.

Consulte el ejemplo que sigue a esta tabla.		 El desencadenador se inicia no antes que la hora de inicio especificada. La primera repetición se basa en la programación que se calcula a partir de la hora de inicio.

Realiza las sucesivas ejecuciones según la programación de periodicidad.
Hora de inicio en el futuro o en el presente Se ejecuta una vez a la hora de inicio especificada.

Realiza ejecuciones posteriores según el cálculo desde la última hora de ejecución.		 El desencadenador se inicia no antes que la hora de inicio especificada. La primera repetición se basa en la programación que se calcula a partir de la hora de inicio.

Realiza las sucesivas ejecuciones según la programación de periodicidad.

Veamos un ejemplo de lo que sucede cuando startTime se encuentra en el pasado, con periodicidad, pero sin programación. Suponga que la hora actual es 2017-04-08 13:00, la hora de inicio es 2017-04-07 14:00, y la periodicidad es cada dos días. (El valor recurrence se define estableciendo la propiedad frequency en day y la propiedad interval en 2). Observe que el valor startTime está en el pasado y se produce antes de la hora actual.

En estas condiciones, la primera ejecución será el 2017-04-09 a las 14:00. El motor de Scheduler calcula las repeticiones de la ejecución desde la hora de inicio. Se descartan las instancias en el pasado. El motor utiliza la instancia siguiente que tiene lugar en el futuro. En este escenario, la hora de inicio será el 2017-04-07 a las 2:00pm, así que la siguiente instancia es dos días a partir de ese momento, que es el 2017-04-09 a las 2:00pm.

La primera vez de ejecución es la misma incluso si el valor startTime es 2017-04-05 14:00 o 2017-04-01 14:00. Después de la primera ejecución, las ejecuciones posteriores se calculan mediante la programación. Por lo tanto, las ejecuciones posteriores se realizan el 2017-04-11 a las 2:00pm, después el 2017-04-13 a las 2:00pm, después el 2017-04-15 a las 2:00pm y así sucesivamente.

Por último, cuando las horas o minutos no se establecen en la programación de un desencadenador, las horas o minutos de la primera ejecución se usan como valores predeterminados.

Propiedad schedule

El uso de una programación puede limitar el número de ejecuciones de desencadenadores. Por ejemplo, si un desencadenador con frecuencia mensual tiene un valor programado para ejecutarse solo el día 31, el desencadenador se ejecuta solo en los meses que tienen 31 días.

Una programación también puede expandir el número de ejecuciones de desencadenadores. Por ejemplo, un desencadenador con una frecuencia mensual programado para ejecutarse en los días primero y segundo del mes, se ejecuta el primer y segundo día del mes, en lugar de una vez al mes.

Si se especifican varios elementos schedule, el orden de evaluación es del valor de programación más grande al más pequeño. La evaluación comienza con el número de semana y luego el día del mes, el día de la semana, la hora y, por último, el minuto.

En la tabla siguiente se describen los elementos schedule en detalle.

Elemento JSON Descripción Valores válidos
minutes Minutos de la hora en la que se ejecuta el desencadenador.
  • Entero
  • Matriz de enteros
hours Horas del día en la que se ejecuta el desencadenador.
  • Entero
  • Matriz de enteros
weekDays Días de la semana en los que se ejecuta el desencadenador. El valor solo se puede especificar con una frecuencia semanal.
  • Lunes, martes, miércoles, jueves, viernes, sábado, domingo.
  • Matriz de valores de día (el tamaño máximo de la matriz es 7).
  • Los valores de día no distinguen mayúsculas de minúsculas.
monthlyOccurrences Días del mes en los que se ejecuta el desencadenador. El valor solo se puede especificar con una frecuencia mensual.
  • Matriz de objetos monthlyOccurrences: { "day": day, "occurrence": occurrence }.
  • El atributo day es el día de la semana en el que se ejecuta el desencadenador. Por ejemplo, una propiedad monthlyOccurrences con un valor day de {Sunday} significa cada domingo del mes. El atributo day es necesario.
  • El atributo occurrence es la ocurrencia del day especificado durante el mes. Por ejemplo, una propiedad monthlyOccurrences con valores day y occurrence de {Sunday, -1} significa el último domingo del mes. El atributo occurrence es opcional.
monthDays Día del mes en el que se ejecuta el desencadenador. El valor solo se puede especificar con una frecuencia mensual.
  • Cualquier valor <= -1 y >= -31
  • Cualquier valor >= 1 y <= 31
  • Matriz de valores

Ejemplos de programaciones de periodicidad del desencadenador

En esta sección se proporcionan ejemplos de programaciones de periodicidad y se centra en el objeto schedule y sus elementos.

En los ejemplos se supone que el interval valor es 1 y que el valor frequency es correcto según la definición de programación. Por ejemplo, no puede tener un valor frequency de day y también tener una modificación monthDays en el objeto schedule. Restricciones como estas se mencionan en la tabla de la sección anterior.

Ejemplo Descripción
{"hours":[5]} Se ejecuta a las 5:00 a. m. todos los días.
{"minutes":[15], "hours":[5]} Se ejecuta a las 5:15 a. m. todos los días.
{"minutes":[15], "hours":[5,17]} Se ejecuta a las 5:15 a. m. y 5:15 p. m. todos los días.
{"minutes":[15,45], "hours":[5,17]} Se ejecuta a las 5:15 a. m., 5:45 a. m., 5:15 p. m. y 5:45 p. m. todos los días.
{"minutes":[0,15,30,45]} Se ejecuta cada 15 minutos.
{hours":[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]} Se ejecuta cada hora. Este desencadenador se ejecuta cada hora. Los minutos se controlan mediante el valor de startTime, cuando se especifica un valor. Si no se especifica un valor, los minutos los controla el tiempo de creación. Por ejemplo, si la hora de inicio o la hora de creación (lo que corresponda) es 12:25 p. m., el desencadenador se ejecuta a las 00:25, 01:25, 02:25… y 23:25.

Esta programación equivale a tener un desencadenador con un valor frequency de hour, un valor de interval de 1 y ningún schedule. Esta programación se puede usar con diferentes valores de frequency y interval para crear otros desencadenadores. Por ejemplo, cuando el valor de frequency es month, la programación se ejecuta solo una vez al mes, en lugar de cada día, cuando el valor de frequency es day.
{"minutes":[0]} Se ejecuta cada hora durante la hora. Este desencadenador se ejecuta cada hora a partir de las 12:00 a. m., 1:00 a. m., 2:00 a. m., y así sucesivamente.

Esta programación es equivalente a un desencadenador con un valor de frequency de hour y un valor startTime de cero minutos, o ningún schedule, sino un valor de frequency de day. Si el valor de frequency es week o month, la programación solo se ejecuta un día a la semana o un día al mes, respectivamente.
{"minutes":[15]} Se ejecuta 15 minutos después de cada hora en punto. Este desencadenador se ejecuta cada hora 15 minutos después de la hora en punto desde las 00:15 a. m., 1:15 a. m., 2:15 a. m. y así sucesivamente, y finalizando a las 11:15 p. m.
{"hours":[17], "weekDays":["saturday"]} Se ejecuta a las 5:00 p. m. los sábados de cada semana.
{"hours":[17], "weekDays":["monday", "wednesday", "friday"]} Se ejecuta a las 5:00 p. m. los lunes, miércoles y viernes de cada semana.
{"minutes":[15,45], "hours":[17], "weekDays":["monday", "wednesday", "friday"]} Se ejecuta a las 5:15 p. m. y 5:45 p. m. los lunes, miércoles y viernes de cada semana.
{"minutes":[0,15,30,45], "weekDays":["monday", "tuesday", "wednesday", "thursday", "friday"]} Se ejecuta cada 15 minutos los días laborables.
{"minutes":[0,15,30,45], "hours": [9, 10, 11, 12, 13, 14, 15, 16] "weekDays":["monday", "tuesday", "wednesday", "thursday", "friday"]} Se ejecuta cada 15 minutos los días laborables entre las 9:00 a. m. y las 4:45 p. m.
{"weekDays":["tuesday", "thursday"]} Se ejecuta los martes y jueves a la hora de inicio especificada.
{"minutes":[0], "hours":[6], "monthDays":[28]} Ejecute a las 6:00 a. m. el día 28 de cada mes (suponiendo un valor frequency de month).
{"minutes":[0], "hours":[6], "monthDays":[-1]} Se ejecuta a las 6:00 a. m. el último día del mes. Para ejecutar un desencadenador el último día del mes, use -1 en lugar del día 28, 29, 30 o 31.
{"minutes":[0], "hours":[6], "monthDays":[1,-1]} Se ejecuta a las 6:00 a. m. el primer y el último día del mes.
{monthDays":[1,14]} Se ejecuta el primer día y el 14 de cada mes a la hora de inicio especificada.
{"minutes":[0], "hours":[5], "monthlyOccurrences":[{"day":"friday", "occurrence":1}]} Se ejecuta el primer viernes de cada mes a las 5:00 a. m.
{"monthlyOccurrences":[{"day":"friday", "occurrence":1}]} Se ejecuta el primer viernes de cada mes a la hora de inicio especificada.
{"monthlyOccurrences":[{"day":"friday", "occurrence":-3}]} Se ejecuta el tercer viernes desde el final del mes, todos los meses, a la hora de inicio especificada.
{"minutes":[15], "hours":[5], "monthlyOccurrences":[{"day":"friday", "occurrence":1},{"day":"friday", "occurrence":-1}]} Se ejecuta el primer viernes de cada mes a las 5:15 a. m.
{"monthlyOccurrences":[{"day":"friday", "occurrence":1},{"day":"friday", "occurrence":-1}]} Se ejecuta el primer y el último viernes de cada mes a la hora de inicio especificada.
{"monthlyOccurrences":[{"day":"friday", "occurrence":5}]} Se ejecuta el quinto viernes de cada mes a la hora de inicio especificada. Cuando no hay ningún quinto viernes en un mes, la canalización no se ejecuta porque está programada para ejecutarse solo los quintos viernes. Para ejecutar el desencadenador el último viernes del mes, considere la posibilidad de usar -1 en lugar de 5 para el valor de occurrence.
{"minutes":[0,15,30,45], "monthlyOccurrences":[{"day":"friday", "occurrence":-1}]} Se ejecuta cada 15 minutos el último viernes del mes.
{"minutes":[15,45], "hours":[5,17], "monthlyOccurrences":[{"day":"wednesday", "occurrence":3}]} Se ejecuta a las 5:15 a. m., 5:45 a. m., 5:15 a. m. y las 5:45 a. m. el tercer miércoles de cada mes.

Contenido relacionado