任務迴圈 - CloudOps Orchestration Service

OOS提供了Task的特殊屬性Loop，其用來支援對單個任務的迴圈。

API類action和雲產品action的任務可支援迴圈，功能性的action（如Trigger、Sleep等）的任務不支援迴圈。

任務迴圈支援並發，不過單步模式執行下迴圈的任務則自動調整為依次執行無並發。

限制

Loop Items的個數限制當前最大為1000個。

文法

YAML文法結構

---
Tasks:
  - Name: TaskName1 # 必填，任務名稱，有效字元為[a-zA-Z0-9_-]，即英文字母數字底線中劃線，長度限制200個字元。建議使用駝峰式命名，如StartInstance。
    Action: TaskType # 必填，任務類型（也叫動作），請參考動作相關的文檔。
    Description: description # 可選，描述，描述當前任務的用途。
    Properties: # 根據所使用的動作不同，具體的屬性列表不同，請參考動作相關的文檔。
      Property1: Value1 # 動作所依賴的屬性和值。
    Outputs:  # 當前任務的輸出參數，可以用作後續任務的輸入或模板的輸出。
      OutputParameterName1:
        Type: TypeName # 可選，輸出參數類型，預設為String。
        ValueSelector: "jq selector" # 如Task是一個OpenAPI調用時，把OpenAPI的調用結果當做一個JSON輸入，應用jq從該JSON中截取所需要的值，請參考雲產品動作和公用模板等具體例子。
    Loop:
      Items: [i-id1,i-id2,i-id3,i-id4] #必填，迴圈元素，可接受一個包含Item的List，遍曆List得到的元素，將作為迴圈任務每次執行時的參數；還可接受一個可被解析為List的參數名，如{{describeInstance.InstanceIds}}。
      RateControl:
          MaxErrors: 0 # 可選，允許數值或百分比的定義方式，如10或10%，預設為0。
          Mode: "Batch/Concurrency" # 必填，迴圈執行速率控制的模式，可選項為Concurrency或Batch；Concurrency表示並發執行，Batch表示分批執行。
          Batch:  [1, 2, 3] # 可選，該參數在Mode=Batch時生效，表示分批控制。定義方式參考下文批次的控制。
          ConcurrencyInBatches: [1, 1, 1]  #可選，該參數在Mode=Batch時生效，表示Batch模式下對每批次的並發度控制，預設20，定義方式為[]內填寫每批對應的並發數。
          Concurrency: 1 # 可選，該參數在Mode=Concurrency時生效，表示所有執行並發數控制，允許數值或百分比。預設為1。
          BatchPauseOption: "FirstBatchPause/Automatic/EveryBatchPause" # 可選，該參數在Mode=Batch時生效，表示分批模式下，每批執行完成後暫停選項。可選項FirstBatchPause/Automatic/EveryBatchPause分別表示首批暫停，自動執行不暫停，每批暫停。
      Outputs:
        FinalOutputParameterName1: #迴圈任務經函數處理後輸出的參數名稱。
          AggregateType: BuiltInFunctionName1 # 選擇一種內建函數方式對輸出進行彙總如Fn::Sum、Fn::Max、Fn::ListJoin。
          AggregateField: OutputParameterName1 # 迴圈的元素執行輸出的參數名稱。

JSON文法結構（請參考YAML注釋說明）

{
  "Tasks": [
    {
      "Name": "TaskName1",
      "Action": "TaskType",
      "Description": "description",
      "Properties": {
        "Property1": "Value1"
      },
      "Outputs": {
        "OutputParameterName1": {
          "Type": "TypeName",
          "ValueSelector": "jq selector"
        }
      },
      "Loop": {
        "Items": [
          "i-id1",
          "i-id2",
          "i-id3",
          "i-id4"
        ],
        "RateControl": {
          "MaxErrors": 0,
          "Mode": "Concurrency/Batch",
          "Batch": [
            1,
            2,
            3
          ],
          "ConcurrencyInBatches": [
            1,
            1,
            1
          ],
          "Concurrency": 1,
          "BatchPauseOption": "FirstBatchPause/Automatic/EveryBatchPause"
        },
        "Outputs": {
          "FinalOutputParameterName1": {
            "AggregateType": "BuiltInFunctionName1",
            "AggregateField": "OutputParameterName1"
          }
        }
      }
    }
  ]
}

迴圈列表Items

Items接受一個List，如一個直接的List：[item1, item2, item3]。

Items也可以是一個List類型的參數名，如上一個Task的List類型Outputs。

Items為一個List。

YAML

Loop:
  Items: [item1,item2,item3,item4] # 一個包含Item的List，如[i-id1,i-id2,i-id3,i-id4]，Items迭代作為Loop所在Task執行的參數。

JSON（請參考YAML注釋說明）

{
  "Items": [
    "item1",
    "item2",
    "item3",
    "item4"
  ]
}

Items為一個List類型的參數名。

YAML

Items: '{{ParameterName1}}' # 一個可被解析為List類型的參數名，如describeInstance.InstanceIds；Items迭代作為Loop所在Task執行的參數。

JSON（請參考YAML注釋說明）

{
  "Items": "{{ParameterName1}}"
}

迴圈執行速率控制

分兩種模式：

並發數控制，保持這個並發數的執行速率，直到所有item執行結束。
批次控制，把item明確地分成多個批次，然後一個批次運行完再運行下一個批次，若上一個批次未全部完成的情況下，下一個批次不會開始。

並發數的控制（Concurrency）

如Items是10個item，並發是3，且會保持一直有3個item在並發，直到沒有更多未執行的item。
- YAML
```
Concurrency: 3 # 允許數值或百分比表並發控制，如3。
Mode: Concurrency
```
- JSON（請參考YAML注釋說明）
```
{
  "Concurrency": 3,
  "Mode": "Concurrency"
}
```
如Items是10個item，並發是20%，表示20%*10=2的並發，且會保持一直有2個item在並發，直到沒有更多未執行的item。
- YAML
```
Concurrency: 20% # 可選，允許數值或百分比的定義方式，如20%。
Mode: Concurrency
```
- JSON（請參考YAML注釋說明）
```
{
  "Concurrency": "20%",
  "Mode": "Concurrency"
}
```

批次的控制（Batch）

如Items是10個item，批次是[3]，會將item分為大小為3的多個批次，結果為3，3，3，1，一共4個批次（假設item的執行結果都是成功）。
- YAML
```
Batch: [1, 2, 3] # 可選，允許List內含數值或百分比的方式定義表批次控制，如[3]。
Mode: Batch
```
- JSON（請參考YAML注釋說明）
```
{
  "Batch": [
    1,
    2,
    3
  ],
  "Mode": "Batch"
}
```
如Items是10個item，批次是[30%]，表示第一個批次是3，會將item分為大小為10*30%=3的多個批次，結果為3，3，3，1，一共4個批次（假設item的執行結果都是成功）：
- YAML
```
Batch: [30%] # 可選，允許List內含數值或百分比的方式定義表批次控制，如[30%]。
Mode: Batch
					
```
- JSON（請參考YAML注釋說明）
```
{
  "Batch": [
    "30%"
  ],
  "Mode": "Batch"
}
```
如Items是10個item，批次是[3,10%,30%]，表示第一個批次是3，第二個批次是總量的10%，第三個及以後批次為[30%]，結果為3，1，3，3一共4個批次（假設item的執行結果都是成功）
- YAML
```
Mode: Batch
Batch: [3, 10%,30%] # 可選，允許List內含多個數值或百分比的方式定義表批次控制，如[3, 10%,30%]。
					
```
- JSON（請參考YAML注釋說明）
```
{
  "Mode": "Batch",
  "Batch": [
    3,
    "10%",
    "30%"
  ]
}
```

錯誤控制MaxErrors

在Loop中，您也可以定義MaxErrors，其意義如下：

允許數值或百分比（表現為Items乘以百分比）的定義方式，如10，或10%。預設為0，即任何錯誤都會暴露到loop-task層級。
Loop裡面的第一個Item，總會被執行。
是否能夠執行到第二個Item或後續的Item取決於實際MaxErrors和ErrorCount的關係。
- 當實際ErrorCount>MaxErrors時，後續的Item停止執行，且當前Loop所在任務標記為失敗。
- 當實際的ErrorCount<=MaxErrors時，則持續向下執行。
根據ErrorCount>MaxErrorsLoop判定Loop所在任務的執行狀態，如果大於則是Failed，否則是Success。

數值方式定義。

YAML

MaxErrors: 2 # 可選，允許數值或百分比的定義方式，如2，表示允許最大ErrorCount為2。

JSON（請參考YAML注釋說明）
```
{
 "MaxErrors": 2 
}
```

百分比方式定義。

YAML

MaxErrors:  25% # 可選，允許數值或百分比的定義方式，如25%，共4個Item則表示允許最大ErrorCount為25%*4=1。

JSON（請參考YAML注釋說明）
```
{
 "MaxErrors": "25%"
}
```

迴圈輸出Loop Outputs

Task或template的Loop也支援outputs，由於Loop的實際outputs中包含多個Item的outputs，因此Loop最終的outputs需要把多個子任務outputs進行彙總，您可通過定義AggreateType來選擇不同內建函數的彙總方式。

定義AggreateType。

YAML

AggregateType: Fn::Max # 選擇一種內建函數對Loop輸出進行彙總，如Fn::Max，表示把所有子任務輸出的Numer類型的最大的OutputParameterName1作為Loop的輸出值。

JSON（請參考YAML注釋說明）

{
"AggregateType": "Fn::Max"
}

樣本

併發模式

YAML格式

FormatVersion: OOS-2019-06-01
Description: Creates one or more ECS instances.
Parameters:
  regionId:
    Description: The ID of region.
    Type: String
    Default: '{{ ACS::RegionId }}'
  imageId:
    Description: The ID of the image resource that you specify when you create the
      instance.
    Type: String
    AllowedPattern: '[A-Za-z0-9_\-\.]*'
    MinLength: 1
    MaxLength: 100
  instanceType:
    Description: The type of the instance.
    Type: String
    AllowedPattern: ecs\.[A-Za-z0-9\.\-]*
    MaxLength: 30
    MinLength: 1
  securityGroupId:
    Description: The ID of the security group to which the instance belongs.
    Type: String
    AllowedPattern: sg-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  vSwitchId:
    Description: The ID of the VSwitch.
    Type: String
    AllowedPattern: vsw-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  amount:
    Description: The specified number of instances you want to create.
    Type: Number
    Default: 1
  internetMaxBandwidthIn:
    Description: The maximum inbound public bandwidth.
    Type: Number
    Default: 200
  internetMaxBandwidthOut:
    Description: The maximum outbound public bandwidth.
    Type: Number
    Default: 0
Tasks:
- Name: runInstances
  Action: ACS::ExecuteAPI
  Description: Creates one or more instances.
  Properties:
    Service: ECS
    API: RunInstances
    Parameters:
      RegionId: '{{ regionId }}'
      Amount: '{{ amount }}'
      ImageId: '{{ imageId }}'
      InstanceType: '{{ instanceType }}'
      SecurityGroupId: '{{ securityGroupId }}'
      VSwitchId: '{{ vSwitchId }}'
      InternetMaxBandwidthIn: '{{ internetMaxBandwidthIn }}'
      InternetMaxBandwidthOut: '{{ internetMaxBandwidthOut }}'
  Outputs:
    instanceIds:
      Type: List
      ValueSelector: InstanceIdSets.InstanceIdSet[]
- Name: untilInstanceReady
  Action: ACS::WaitFor
  Description: Waits for the created instances to be Running.
  Properties:
    Service: ECS
    API: DescribeInstances
    Parameters:
      RegionId: '{{ regionId }}'
      InstanceIds:
      - '{{ ACS::TaskLoopItem }}'
    DesiredValues:
    - Running
    PropertySelector: Instances.Instance[].Status
  Loop:
    RateControl:
      Mode: Concurrency
      MaxErrors: 0
      Concurrency: 1
    Items: '{{ runInstances.instanceIds }}'
Outputs:
  instanceIds:
    Type: List
    Value: '{{ runInstances.instanceIds }}'

JSON格式

{
  "FormatVersion": "OOS-2019-06-01",
  "Description": "Creates one or more ECS instances.",
  "Parameters": {
    "regionId": {
      "Description": "The ID of region.",
      "Type": "String",
      "Default": "{{ ACS::RegionId }}"
    },
    "imageId": {
      "Description": "The ID of the image resource that you specify when you create the instance.",
      "Type": "String",
      "AllowedPattern": "[A-Za-z0-9_\\-\\.]*",
      "MinLength": 1,
      "MaxLength": 100
    },
    "instanceType": {
      "Description": "The type of the instance.",
      "Type": "String",
      "AllowedPattern": "ecs\\.[A-Za-z0-9\\.\\-]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "securityGroupId": {
      "Description": "The ID of the security group to which the instance belongs.",
      "Type": "String",
      "AllowedPattern": "sg-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "vSwitchId": {
      "Description": "The ID of the VSwitch.",
      "Type": "String",
      "AllowedPattern": "vsw-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "amount": {
      "Description": "The specified number of instances you want to create.",
      "Type": "Number",
      "Default": 1
    },
    "internetMaxBandwidthIn": {
      "Description": "The maximum inbound public bandwidth.",
      "Type": "Number",
      "Default": 200
    },
    "internetMaxBandwidthOut": {
      "Description": "The maximum outbound public bandwidth.",
      "Type": "Number",
      "Default": 0
    }
  },
  "Tasks": [
    {
      "Name": "runInstances",
      "Action": "ACS::ExecuteAPI",
      "Description": "Creates one or more instances.",
      "Properties": {
        "Service": "ECS",
        "API": "RunInstances",
        "Parameters": {
          "RegionId": "{{ regionId }}",
          "Amount": "{{ amount }}",
          "ImageId": "{{ imageId }}",
          "InstanceType": "{{ instanceType }}",
          "SecurityGroupId": "{{ securityGroupId }}",
          "VSwitchId": "{{ vSwitchId }}",
          "InternetMaxBandwidthIn": "{{ internetMaxBandwidthIn }}",
          "InternetMaxBandwidthOut": "{{ internetMaxBandwidthOut }}"
        }
      },
      "Outputs": {
        "instanceIds": {
          "Type": "List",
          "ValueSelector": "InstanceIdSets.InstanceIdSet[]"
        }
      }
    },
    {
      "Name": "untilInstanceReady",
      "Action": "ACS::WaitFor",
      "Description": "Waits for the created instances to be Running.",
      "Properties": {
        "Service": "ECS",
        "API": "DescribeInstances",
        "Parameters": {
          "RegionId": "{{ regionId }}",
          "InstanceIds": [
            "{{ ACS::TaskLoopItem }}"
          ]
        },
        "DesiredValues": [
          "Running"
        ],
        "PropertySelector": "Instances.Instance[].Status"
      },
      "Loop": {
        "RateControl": {
          "Mode": "Concurrency",
          "MaxErrors": 0,
          "Concurrency": 1
        },
        "Items": "{{ runInstances.instanceIds }}"
      }
    }
  ],
  "Outputs": {
    "instanceIds": {
      "Type": "List",
      "Value": "{{ runInstances.instanceIds }}"
    }
  }
}

分批模式

YAML格式

FormatVersion: OOS-2019-06-01
Description: Creates one or more ECS instances.
Parameters:
  regionId:
    Description: The ID of region.
    Type: String
    Default: '{{ ACS::RegionId }}'
  imageId:
    Description: The ID of the image resource that you specify when you create the
      instance.
    Type: String
    AllowedPattern: '[A-Za-z0-9_\-\.]*'
    MinLength: 1
    MaxLength: 100
  instanceType:
    Description: The type of the instance.
    Type: String
    AllowedPattern: ecs\.[A-Za-z0-9\.\-]*
    MaxLength: 30
    MinLength: 1
  securityGroupId:
    Description: The ID of the security group to which the instance belongs.
    Type: String
    AllowedPattern: sg-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  vSwitchId:
    Description: The ID of the VSwitch.
    Type: String
    AllowedPattern: vsw-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  amount:
    Description: The specified number of instances you want to create.
    Type: Number
    Default: 1
  internetMaxBandwidthIn:
    Description: The maximum inbound public bandwidth.
    Type: Number
    Default: 200
  internetMaxBandwidthOut:
    Description: The maximum outbound public bandwidth.
    Type: Number
    Default: 0
Tasks:
- Name: runInstances
  Action: ACS::ExecuteAPI
  Description: Creates one or more instances.
  Properties:
    Service: ECS
    API: RunInstances
    Parameters:
      RegionId: '{{ regionId }}'
      Amount: '{{ amount }}'
      ImageId: '{{ imageId }}'
      InstanceType: '{{ instanceType }}'
      SecurityGroupId: '{{ securityGroupId }}'
      VSwitchId: '{{ vSwitchId }}'
      InternetMaxBandwidthIn: '{{ internetMaxBandwidthIn }}'
      InternetMaxBandwidthOut: '{{ internetMaxBandwidthOut }}'
  Outputs:
    instanceIds:
      Type: List
      ValueSelector: InstanceIdSets.InstanceIdSet[]
- Name: untilInstanceReady
  Action: ACS::WaitFor
  Description: Waits for the created instances to be Running.
  Properties:
    Service: ECS
    API: DescribeInstances
    Parameters:
      RegionId: '{{ regionId }}'
      InstanceIds:
      - '{{ ACS::TaskLoopItem }}'
    DesiredValues:
    - Running
    PropertySelector: Instances.Instance[].Status
  Loop:
    RateControl:
      Mode: Concurrency
      MaxErrors: 0
      Concurrency: 1
    Items: '{{ runInstances.instanceIds }}'
Outputs:
  instanceIds:
    Type: List
    Value: '{{ runInstances.instanceIds }}'

JSON格式

{
  "FormatVersion": "OOS-2019-06-01",
  "Description": "Creates one or more ECS instances.",
  "Parameters": {
    "regionId": {
      "Description": "The ID of region.",
      "Type": "String",
      "Default": "{{ ACS::RegionId }}"
    },
    "imageId": {
      "Description": "The ID of the image resource that you specify when you create the instance.",
      "Type": "String",
      "AllowedPattern": "[A-Za-z0-9_\\-\\.]*",
      "MinLength": 1,
      "MaxLength": 100
    },
    "instanceType": {
      "Description": "The type of the instance.",
      "Type": "String",
      "AllowedPattern": "ecs\\.[A-Za-z0-9\\.\\-]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "securityGroupId": {
      "Description": "The ID of the security group to which the instance belongs.",
      "Type": "String",
      "AllowedPattern": "sg-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "vSwitchId": {
      "Description": "The ID of the VSwitch.",
      "Type": "String",
      "AllowedPattern": "vsw-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "amount": {
      "Description": "The specified number of instances you want to create.",
      "Type": "Number",
      "Default": 1
    },
    "internetMaxBandwidthIn": {
      "Description": "The maximum inbound public bandwidth.",
      "Type": "Number",
      "Default": 200
    },
    "internetMaxBandwidthOut": {
      "Description": "The maximum outbound public bandwidth.",
      "Type": "Number",
      "Default": 0
    }
  },
  "Tasks": [
    {
      "Name": "runInstances",
      "Action": "ACS::ExecuteAPI",
      "Description": "Creates one or more instances.",
      "Properties": {
        "Service": "ECS",
        "API": "RunInstances",
        "Parameters": {
          "RegionId": "{{ regionId }}",
          "Amount": "{{ amount }}",
          "ImageId": "{{ imageId }}",
          "InstanceType": "{{ instanceType }}",
          "SecurityGroupId": "{{ securityGroupId }}",
          "VSwitchId": "{{ vSwitchId }}",
          "InternetMaxBandwidthIn": "{{ internetMaxBandwidthIn }}",
          "InternetMaxBandwidthOut": "{{ internetMaxBandwidthOut }}"
        }
      },
      "Outputs": {
        "instanceIds": {
          "Type": "List",
          "ValueSelector": "InstanceIdSets.InstanceIdSet[]"
        }
      }
    },
    {
      "Name": "untilInstanceReady",
      "Action": "ACS::WaitFor",
      "Description": "Waits for the created instances to be Running.",
      "Properties": {
        "Service": "ECS",
        "API": "DescribeInstances",
        "Parameters": {
          "RegionId": "{{ regionId }}",
          "InstanceIds": [
            "{{ ACS::TaskLoopItem }}"
          ]
        },
        "DesiredValues": [
          "Running"
        ],
        "PropertySelector": "Instances.Instance[].Status"
      },
      "Loop": {
        "RateControl": {
          "Mode": "Concurrency",
          "MaxErrors": 0,
          "Concurrency": 1
        },
        "Items": "{{ runInstances.instanceIds }}"
      }
    }
  ],
  "Outputs": {
    "instanceIds": {
      "Type": "List",
      "Value": "{{ runInstances.instanceIds }}"
    }
  }
}