建立依輪轉視窗執行管線的觸發程序

發行項
07/15/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。了解如何免費開始新的試用！

本文章提供建立、啟動、監視輪轉視窗觸發程序的步驟。如需觸發程序及支援類型的詳細資訊，請參閱管線執行和觸發程序。

輪轉視窗觸發程序是可從指定的開始時間定期引發，同時還能保留狀態的一種觸發程序。輪轉視窗範圍是一系列大小固定、非重疊的連續時間間隔。輪轉視窗觸發程序與管線會有一對一的關係，並只能參考單一管線。

對於排程觸發程序來說，輪轉視窗觸發程序是更重要的替代方案。其可為複雜的案例提供一套功能 (例如，相依於其他輪轉視窗觸發程序、重新執行失敗的作業，以及設定管線的使用者重試)。若要進一步瞭解排程觸發程序和輪轉視窗觸發程序之間的差異，請參閱觸發程序類型比較。

Azure Data Factory 和 Azure Synapse 入口網站體驗

若要在 Azure 入口網站中建立輪轉時間範圍觸發程序，請選取 [觸發程序] 索引標籤，然後選取 [新增]。
觸發程序組態窗格開啟之後，選取 [輪轉視窗]。然後定義輪轉視窗觸發程序屬性。
完成之後，選取儲存。

Azure Data Factory
Azure Synapse

在 Azure 入口網站的 Data Factory 中顯示建立輪轉視窗觸發程序的螢幕擷取畫面。

輪轉視窗觸發程序類型屬性

輪轉視窗有下列觸發程序類型屬性：

{
    "name": "MyTriggerName",
    "properties": {
        "type": "TumblingWindowTrigger",
        "runtimeState": "<<Started/Stopped/Disabled - readonly>>",
        "typeProperties": {
            "frequency": <<Minute/Hour>>,
            "interval": <<int>>,
            "startTime": "<<datetime>>",
            "endTime": <<datetime - optional>>,
            "delay": <<timespan - optional>>,
            "maxConcurrency": <<int>> (required, max allowed: 50),
            "retryPolicy": {
                "count": <<int - optional, default: 0>>,
                "intervalInSeconds": <<int>>,
            },
            "dependsOn": [
                {
                    "type": "TumblingWindowTriggerDependencyReference",
                    "size": <<timespan - optional>>,
                    "offset": <<timespan - optional>>,
                    "referenceTrigger": {
                        "referenceName": "MyTumblingWindowDependency1",
                        "type": "TriggerReference"
                    }
                },
                {
                    "type": "SelfDependencyTumblingWindowTriggerReference",
                    "size": <<timespan - optional>>,
                    "offset": <<timespan>>
                }
            ]
        },
        "pipeline": {
            "pipelineReference": {
                "type": "PipelineReference",
                "referenceName": "MyPipelineName"
            },
            "parameters": {
                "parameter1": {
                    "type": "Expression",
                    "value": "@{concat('output',formatDateTime(trigger().outputs.windowStartTime,'-dd-MM-yyyy-HH-mm-ss-ffff'))}"
                },
                "parameter2": {
                    "type": "Expression",
                    "value": "@{concat('output',formatDateTime(trigger().outputs.windowEndTime,'-dd-MM-yyyy-HH-mm-ss-ffff'))}"
                },
                "parameter3": "https://mydemo.azurewebsites.net/api/demoapi"
            }
        }
    }
}

下表提供與輪轉視窗觸發程序之週期和排程相關的主要 JSON 元素的概要概觀。

JSON 元素	描述	類型	允許的值	必要
`type`	觸發程序的類型。 `type` 是固定值 `TumblingWindowTrigger`。	`String`	`TumblingWindowTrigger`	Yes
`runtimeState`	觸發程序執行時間的目前狀態。此元素是 <readOnly>。	`String`	`Started`、`Stopped`、`Disabled`	Yes
`frequency`	一個字串，代表觸發程序一再執行的頻率單位 (分鐘、小時或月)。如果 `startTime` 日期值比 `frequency` 值更細微，則在計算視窗界限時會將 `startTime` 日期納入計算。例如，如果 `frequency` 值是 `hourly`，而 `startTime` 值是 2017-09-01T10:10:10Z，則第一個視窗是 (2017-09-01T10:10:10Z, 2017-09-01T11:10:10Z)。	`String`	`Minute`、`Hour`、`Month`	Yes
`interval`	代表 `frequency` 值之間隔的整數值，用來決定觸發程序執行的頻率。例如，如果 `interval` 是 `3`，且 `frequency` 是 `hour`，則觸發程序會每隔 3 小時重複一次。視窗間隔下限為 5 分鐘。	`Integer`	正整數。	Yes
`startTime`	第一次出現，可以是過去。第一個觸發間隔是 (`startTime`, `startTime + interval`)。	`DateTime`	`DateTime` 值。	Yes
`endTime`	最後一次出現，可以是過去。	`DateTime`	`DateTime` 值。	Yes
`delay`	視窗延遲開始資料處理所延遲的時間長度。管線執行會在預期執行時間加上 delay 後開始。 delay 定義觸發程序要在超過到期時間多久之後，才觸發新的執行。 delay 不會改變視窗的 `startTime`。例如，`delay` 值為 00:10:00 表示延遲 10 分鐘。	`Timespan` (hh:mm:ss)	`timespan` 值，預設值是 `00:00:00`。	No
`maxConcurrency`	就緒視窗可引發的同時執行觸發程序數目。例如，為昨天回填每小時執行，結果會有 24 個視窗。如果 `maxConcurrency` = 10，只有前 10 個視窗 (00:00-01:00 - 00:09:00-10) 會引發觸發程序事件。前 10 個觸發的管線執行完成之後，才會引發接下來 10 個視窗 (10:00-11:00 - 19:00 20:00) 的觸發程序執行。繼續以本範例的 `maxConcurrency` = 10 說明，如果有 10 個就緒視窗，則總共會有 10 個管線執行。如果只有一個視窗就緒，則只會執行一個管線。	`Integer`	1 到 50 之間的整數。	Yes
`retryPolicy: Count`	到管線執行標示為 `Failed` 前的重試次數。	`Integer`	整數，預設值為 0 (無重試)。	No
`retryPolicy: intervalInSeconds`	重試嘗試之間的延遲 (以秒指定)	`Integer`	秒數，預設值是 30。最小值為 `30`。	No
`dependsOn: type`	`TumblingWindowTriggerReference` 的類型。若已設定相依性，則為必要。	`String`	`TumblingWindowTriggerDependencyReference`, `SelfDependencyTumblingWindowTriggerReference`	No
`dependsOn: size`	相依性輪轉時間範圍的大小。	`Timespan` (hh:mm:ss)	正數的 `timespan` 值，其預設值為子觸發程序的視窗大小。	No
`dependsOn: offset`	相依性觸發程序的位移。	`Timespan` (hh:mm:ss)	在自我相依性中必須是負數的 `timespan` 值。如果未指定任何值，則視窗會與觸發程序本身相同。	自我相依性：是其他：否

注意

發佈輪轉視窗觸發程序之後，便無法編輯 interval 和 frequency。

WindowStart 和 WindowEnd 系統變數

您可以在您的 pipeline (管線) 定義中使用輪轉視窗觸發程序的 WindowStart 和 WindowEnd 系統變數 (也是查詢的一部分)。將系統變數當作參數傳遞給 trigger (觸發程序) 定義中的管線。以下範例示範如何將這些變數當作參數傳遞。

{
    "name": "MyTriggerName",
    "properties": {
        "type": "TumblingWindowTrigger",
            ...
        "pipeline": {
            "pipelineReference": {
                "type": "PipelineReference",
                "referenceName": "MyPipelineName"
            },
            "parameters": {
                "MyWindowStart": {
                    "type": "Expression",
                    "value": "@{concat('output',formatDateTime(trigger().outputs.windowStartTime,'-dd-MM-yyyy-HH-mm-ss-ffff'))}"
                },
                "MyWindowEnd": {
                    "type": "Expression",
                    "value": "@{concat('output',formatDateTime(trigger().outputs.windowEndTime,'-dd-MM-yyyy-HH-mm-ss-ffff'))}"
                }
            }
        }
    }
}

若要在管線定義中使用 WindowStart 和 WindowEnd 系統變數值，請據以使用您的 MyWindowStart 和 MyWindowEnd 參數。

回填案例的視窗執行順序

如果觸發程序的 startTime 在過去，則根據此公式 M=(CurrentTime- TriggerStartTime)/TumblingWindowSize，觸發程序會先平行產生 {M} backfill(past) 執行，並接受觸發程序並行，再執行未來的執行。時間範圍的執行順序具決定性，從最舊到最新的間隔。目前無法修改此行為。

注意

在此情況下，會先從選取 startTime 執行所有執行，再執行未來的執行。如果您需要回填很長一段時間，建議您執行初始歷程記錄負載。

現有 TriggerResource 元素

下列各點適用於更新現有的 TriggerResource 元素：

建立觸發程序後，便無法變更觸發程序的 frequency 元素 (或視窗大小) 以及 interval 元素的值。若要讓 triggerRun 重新執行和相依性評估正常運作，則此限制為必要。
如果觸發程序的 endTime 元素值變更 (新增或更新)，則已經處理的視窗狀態「不會」重設。觸發程序會採用新的 endTime 值。如果新的 endTime 值在已經執行的視窗之前，觸發程序會停止。反之，觸發程序會在遇到新的 endTime 值時停止。

使用者指派的管線重試

如果管線失敗，輪轉視窗觸發程序可以使用相同的輸入參數自動重試參考管線的執行，而不需要使用者介入。使用觸發程序定義中的 retryPolicy 屬性來指定此動作。

輪轉時間範圍觸發程序相依性

如果您想要確定只有在資料處理站中成功執行另一個輪轉時間範圍觸發程序之後，才會執行輪轉時間範圍觸發程序，請建立輪轉時間範圍觸發程序相依性。

取消輪轉視窗執行

如果特定視窗處於 [等候中]、[正在等候相依性] 或 [執行中] 狀態，您可以取消輪轉視窗觸發程序的執行：

如果視窗處於 [執行中] 狀態，請取消相關聯的 [管線執行]，且觸發程序執行之後會標示為 [已取消]。
如果視窗處於 [等候中] 或 [正在等候相依性] 狀態，您可以從 [監視] 取消視窗。

Azure Data Factory
Azure Synapse

顯示從 Data Factory [監視] 頁面取消輪轉視窗觸發程序的螢幕擷取畫面。

您也可以重新執行已取消的時間範圍。重新執行會採用觸發程序的最新已發佈定義。指定視窗的相依性會在重新執行時重新評估。

Azure Data Factory
Azure Synapse

螢幕擷取畫面顯示先前在 Data Factory 中取消執行的輪轉視窗觸發程序重新執行。

本節說明如何使用 Azure PowerShell 來建立、啟動及監視觸發程序。

注意

建議您使用 Azure Az PowerShell 模組來與 Azure 互動。若要開始使用，請參閱安裝 Azure PowerShell (部分機器翻譯)。若要了解如何移轉至 Az PowerShell 模組，請參閱將 Azure PowerShell 從 AzureRM 移轉至 Az。

必要條件

Azure 訂用帳戶：如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
Azure PowerShell：請遵循使用 PowerShellGet 在 Windows 上安裝 Azure PowerShell 中的指示操作。
Azure Data Factory：請遵循使用 PowerShell 建立 Azure Data Factory 中的指示，建立資料處理站和管線。

範例指令碼

在 C:\ADFv2QuickStartPSH\ 資料夾中，使用下列內容建立名為 MyTrigger.json 的 JSON 檔案：

重要

在您儲存 JSON 檔案之前，請先將 startTime 元素的值設定為目前的國際標準時間 (UTC) 時間。將 endTime 元素的值設定為目前 UTC 時間的一小時之後。

{
  "name": "PerfTWTrigger",
  "properties": {
    "type": "TumblingWindowTrigger",
    "typeProperties": {
      "frequency": "Minute",
      "interval": "15",
      "startTime": "2017-09-08T05:30:00Z",
      "endTime" : "2017-09-08T06:30:00Z",
      "delay": "00:00:01",
      "retryPolicy": {
        "count": 2,
        "intervalInSeconds": 30
      },
      "maxConcurrency": 50
    },
    "pipeline": {
      "pipelineReference": {
        "type": "PipelineReference",
        "referenceName": "DynamicsToBlobPerfPipeline"
      },
      "parameters": {
        "windowStart": "@trigger().outputs.windowStartTime",
        "windowEnd": "@trigger().outputs.windowEndTime"
      }
    },
    "runtimeState": "Started"
  }
}

使用 Set-AzDataFactoryV2Trigger Cmdlet 建立觸發程序：

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

使用 Get-AzDataFactoryV2Trigger Cmdlet，確認觸發程序的狀態為 Stopped：

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

使用 Start-AzDataFactoryV2Trigger Cmdlet 啟動觸發程序：

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

使用 Get-AzDataFactoryV2Trigger Cmdlet，確認觸發程序的狀態為 Started：

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

使用 Get-AzDataFactoryV2TriggerRun Cmdlet，取得 Azure PowerShell 中的觸發程序執行。若要取得有關觸發程序執行的資訊，請定期執行以下命令。更新 TriggerRunStartedAfter 和 TriggerRunStartedBefore 值，以符合觸發程序定義中的值：
```
Get-AzDataFactoryV2TriggerRun -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -TriggerName "MyTrigger" -TriggerRunStartedAfter "2017-12-08T00:00:00" -TriggerRunStartedBefore "2017-12-08T01:00:00"
```

本節說明如何使用 Azure CLI 來建立、啟動及監視觸發程序。

必要條件

在 Azure Cloud Shell 中使用 Bash 環境。如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 登入。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

請遵循使用 Azure CLI 建立 Azure Data Factory 中的指示，建立資料處理站和管線。

範例指令碼

在工作目錄中，使用觸發程式的屬性建立名為 MyTrigger.json 的 JSON 檔案。針對此範例，使用下列內容：

重要

儲存 JSON 檔案之前，將 referenceName 的值設定為您的管線名稱。將 startTime 元素的值設定為目前的 UTC 時間。將 endTime 元素的值設定為目前 UTC 時間的一小時之後。

{
    "type": "TumblingWindowTrigger",
    "typeProperties": {
      "frequency": "Minute",
      "interval": "15",
      "startTime": "2017-12-08T00:00:00Z",
      "endTime": "2017-12-08T01:00:00Z",
      "delay": "00:00:01",
      "retryPolicy": {
        "count": 2,
        "intervalInSeconds": 30
      },
      "maxConcurrency": 50
    },
    "pipeline": {
      "pipelineReference": {
        "type": "PipelineReference",
        "referenceName": "DynamicsToBlobPerfPipeline"
      },
      "parameters": {
        "windowStart": "@trigger().outputs.windowStartTime",
        "windowEnd": "@trigger().outputs.windowEndTime"
      }
    },
    "runtimeState": "Started"
}

使用 az datafactory trigger create 命令建立觸發程序：

重要

針對此步驟和所有後續步驟，以您的資源群組名稱取代 ResourceGroupName。以資料處理站的名稱取代 DataFactoryName。
```
az datafactory trigger create --resource-group "ResourceGroupName" --factory-name "DataFactoryName"  --name "MyTrigger" --properties @MyTrigger.json  
```

使用 az datafactory trigger show 命令，確認觸發程序的狀態為 Stopped：

az datafactory trigger show --resource-group "ResourceGroupName" --factory-name "DataFactoryName" --name "MyTrigger"

使用 az datafactory trigger start 命令啟動觸發程序：

az datafactory trigger start --resource-group "ResourceGroupName" --factory-name "DataFactoryName" --name "MyTrigger"

使用 az datafactory trigger show 命令，確認觸發程序的狀態為 Started：

az datafactory trigger show --resource-group "ResourceGroupName" --factory-name "DataFactoryName" --name "MyTrigger"

使用 az datafactory trigger-run query-by-factory 命令，取得 Azure CLI 中的觸發程序執行。若要取得有關觸發程序執行的資訊，請定期執行以下命令。更新 last-updated-after 和 last-updated-before 值，以符合觸發程序定義中的值：

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

若要在 Azure 入口網站中監視觸發程序執行和管線執行，請參閱監視管線執行。

共用方式為

建立依輪轉視窗執行管線的觸發程序

Azure Data Factory 和 Azure Synapse 入口網站體驗

輪轉視窗觸發程序類型屬性

WindowStart 和 WindowEnd 系統變數

回填案例的視窗執行順序

現有 TriggerResource 元素

使用者指派的管線重試

輪轉時間範圍觸發程序相依性

取消輪轉視窗執行

Azure PowerShell 和 Azure CLI 範例

必要條件

範例指令碼

必要條件

範例指令碼

意見反應

其他資源

共用方式為

建立依輪轉視窗執行管線的觸發程序

Azure Data Factory 和 Azure Synapse 入口網站體驗

輪轉視窗觸發程序類型屬性

WindowStart 和 WindowEnd 系統變數

回填案例的視窗執行順序

現有 TriggerResource 元素

使用者指派的管線重試

輪轉時間範圍觸發程序相依性

取消輪轉視窗執行

Azure PowerShell 和 Azure CLI 範例

必要條件

範例指令碼

相關內容

意見反應

其他資源