什麼是內建函數Builtin-Functions - CloudOps Orchestration Service

OOS提供了多個內建函數，可以在定義條件（Conditions）、定義模板任務（Task）屬性或模板輸出（Output）時使用該類函數，使您更加方便地處理模板的參數及輸出結果。

函數說明

內建函數名	描述
Fn::Base64Encode	返回輸入字串的Base64編碼結果。
Fn::Base64Decode	返回輸入字串的Base64解碼結果。
Fn::MergeMapToList	將多個Map合并成一個以Map為元素的列表。
Fn::MergeMap	將列表中多個Map合并成一個Map。
Fn::Join	將一組值串連起來，用特定分隔字元隔開。
Fn::Select	資料元容器通過查詢索引返回的單個資料元。
Fn::Split	通過指定分隔字元對字串進行切片，並返回所有切片組成的列表。
Fn::Replace	將字串中指定子字串用新字串替換。
Fn::Min	返回列表中最小元素。
Fn::Max	返回列表中最大元素。
Fn::First	返回列表中第一個元素。
Fn::Last	返回列表中最後一個元素。
Fn::ListJoin	將多個參數轉換成列表。
Fn::Equals	比較兩個值是否相等。
Fn::If	根據判斷條件真假返回不同的值。
Fn::Not	對值取否操作。
Fn::AddHour	對一個UTC時間向後推移N小時。
Fn::FormatUTCTime	按不同單位精度進行格式化UTC時間。
Fn::Eval	執行字串中的單行運算式，並返回執行結果。
Fn::CalculateTimeByOpsWindow	當指定一個時間視窗後，該函數會根據函數的執行時間點，產生下一個在視窗區間的時間點。
Fn::And	邏輯與。
Fn::Or	邏輯或。
Fn::Intersection	取多個數組的交集。
Fn::Union	取多個數組的並集。
Fn::Difference	取多個數組的並集與交集的差集。
Fn::Jq	對JSON對象進行篩選，擷取目標屬性值。
Fn::MapJoin	將兩個List組合成一個Map，組合時，會把第一個List內的所有值，作為Map中每個索引值對的鍵，會把第二個List內的值，作為Map中每個索引值對。
Fn::IsIpInCIDR	判斷指定的IP是否在指定的CIDR網段內。
Fn::Sub	將輸入字串中的變數替換為指定的值。
Fn::DurationBetween	返回兩個時間點之間的時間長度。
Fn::Escape	逸出字元串。
Fn::ConvertMapToList	轉化JSON對象為Key、Value格式的列表。

使用情境

內建函數主要使用在定義條件（Conditions）、定義模板任務（Task）或模板輸出（Output）階段，用來對任務輸出、引用參數或使用者定義的值進行處理，以得到希望的結果，具體使用樣本如下：

條件（Conditions）：

在定義條件時，使用到內建函數Fn::Equals。

Conditions:
  NewTemporaryEcs:
    Fn::Equals:
      - '{{ buildType }}'
      - NewTemporaryEcs

任務（Task）：

在任務中設定When或Properties屬性時，使用到內建函數Fn::Equals。

FormatVersion: OOS-2019-06-01
Description: 執行單個API
Tasks:
  - Name: ExecuteApi
    Action: ACS::ExecuteApi
    When: 
      Fn::Equals:
        - '{{ param }}'
        - true
    Description:
      en: Perform a single ExecuteApi operation.
      zh-cn: 執行API
    Properties:
      Service: ecs
      API: DescribeRegions
      Parameters:
        InstanceChargeType:
          Fn::Equals:
            - 1
            - 1
        ResourceType: ''

模板輸出（Output）：

模板輸出值也可以根據您的需要使用內建函數進行處理。

Outputs:

 invocationOutput:
 Type: String
 Value:
 'Fn::Base64Decode': '{{ describeInvocationResults.invocationResult }}'

內建函數使用樣本

內建函數的使用主要由內建函數名和待處理參數組成。調用函數的聲明運算式即表示函數處理參數後返回的結果，且運算式作為函數返回的結果可以像其他參數一樣被引用。

Fn::Base64Encode

返回輸入字串的Base64編碼結果。

聲明

{"Fn::Base64Encode": "StringToBeBase64"}

參數

StringToBeBase64：要進行Base64編碼的String。

傳回值

Base64方式表示的原始字串。

樣本

{"Fn::Base64Encode": "hello"}

樣本返回

"aGVsbG8="

Fn::Base64Decode

返回Base64字串的解碼結果。

聲明

{"Fn::Base64Decode": "Base64ToBeString"}

參數

Base64ToBeString：Base64編碼方式表示的String。

傳回值

Base64解碼後的原始String。

樣本

{"Fn::Base64Decode": "aGVsbG8="}

樣本返回

"hello"

Fn::MergeMapToList

將多個Map合并成一個以Map為元素的列表。

聲明

{"Fn::MergeMapToList": "aListConatinsDicts"}

參數

aListConatinsDicts：含有多個映射的List。

傳回值

一個以Map為元素的List。

樣本1

{
  "Fn::MergeMapToList": [
    {
      "key_1": [
        "key_1_item_1",
        "key_1_item_2"
      ]
    },
    {
      "key_2": [
        "key_2_item_1",
        "key_2_item_2"
      ]
    },
    {
      "key_3": [
        "key_3_item_1",
        "key_3_item_2"
      ]
    }
  ]
}

樣本1返回

[
  {
    "key_1": "key_1_item_1",
    "key_2": "key_2_item_1",
    "key_3": "key_3_item_1"
  },
  {
    "key_1": "key_1_item_2",
    "key_2": "key_2_item_2",
    "key_3": "key_3_item_2"
  }
]

樣本2

{
  "Fn::MergeMapToList": [
    {
      "key_1": [
        "key_1_item_1",
        "key_1_item_2"
      ]
    },
    {
      "key_2": [
        "key_2_item_1",
        "key_2_item_2",
        "key_2_item_3"
      ]
    },
    {
      "key_3": [
        "key_3_item_1",
        "key_3_item_2"
      ]
    }
  ]
}

樣本2返回

[  
   {
      "key_1": "key_1_item_1", 
      "key_2": "key_2_item_1",
      "key_3": "key_3_item_1"
    },
    {
      "key_1": "key_1_item_2", 
      "key_2": "key_2_item_2",
      "key_3": "key_3_item_2"
    },
    {
      "key_1": "key_1_item_2", 
      "key_2": "key_2_item_3",
      "key_3": "key_3_item_2"
    }
]

Fn::MergeMap

將列表中多個Map合并成一個Map。

聲明

{  "Fn::MergeMap": "aListConatinsDicts"}

參數

aListConatinsDicts：含有多個映射的List。

傳回值

List中多個Map合并成的一個Map。

樣本

{
  "Fn::MergeMap": [
    {
      "key_1": "value_1"
    },
    {
      "key_2": "value_2"
    }
  ]
}

樣本返回

{"key_1": "value_1","key_2": "value_2"}

Fn::Join

將一組值串連起來，用特定分隔字元隔開。

聲明

{"Fn::Join": ["Connector","aListContainsString"]}

參數

Connector：作為串連符String。
aListContainsString：包含字串的List。

傳回值

List內多個元素串連後的字串。

樣本

{
  "Fn::Join": [
    ",",
    [
      "a",
      "b",
      "c"
    ]
  ]
}

樣本返回

"a,b,c"

Fn::Select

資料元容器通過查詢索引返回的單個資料元。

聲明

{"Fn::Select": ["Index","Container"]}

參數

Index：被查詢Container的索引String或Number。
Container：被查詢的List或Map。

傳回值

查詢指定索引返回的結果。

樣本1

{
  "Fn::Select": [
    "IpAddress",
    {
      "IpAddress": [
        "192.168.1.123",
        "192.168.1.234"
      ]
    }
  ]
}

樣本1返回

["192.168.1.123","192.168.1.234"]

樣本2

{
  "Fn::Select": [
    "1",
    [
      "192.168.1.123",
      "192.168.1.234"
    ]
  ]
}

樣本2返回

"192.168.1.234"

Fn::Split

通過指定分隔字元對字串進行切片，並返回所有切片組成的列表。

聲明

{"Fn::Split": ["Separator","StringToSeprate"]}

參數

Separator：作為分隔字元的String。
StringToSeparate：將被按分隔字元分成一個List的String。

傳回值

StringToSeparate按分隔字元分成的一個List。

樣本

{
  "Fn:: Split": [",","a,b,c"]
}

樣本返回

[
  "a",
  "b",
  "c"
]

Fn::Replace

將字串中指定子字串用新字串替換。

聲明

{  "Fn::Replace": [{"$varName": "StringToReplaceWith"}, "StringToReplace"]}

參數

$varName：預留位置，以$開始後面串連普通參數名即可，其中$後面參數名命名要求同模板參數名。
StringToReplaceWith：預留位置將被替換成的值。
StringToReplace：將被替換的值（含預留位置），如"$varName is foo"。

傳回值

若參數StringToReplaceWith是"baz"，則返回為"baz is foo"。

樣本

{  "Fn::Replace": [{"$varName": "baz"},    "$varName is foo"  ]}

樣本返回

"baz is foo"

Fn::Min

返回列表中最小元素。

聲明

{"Fn::Min": "aList"}

參數

aList：一個含有元素的List；List中元素類型可以為string,int,datetime,None，各元素必須為同一類型。

傳回值

忽略值為None的元素，返回List中最小的元素，若集合元素全部為None則返回None。

樣本

{
  "Fn::Min": ["123","234"]
}

樣本返回

"123"

Fn::Max

返回列表中最大元素。

聲明

{"Fn::Max": "aList"}

參數

aList：一個含有元素的List；List中元素類型可以為string、int、datetime、None，各元素必須為同一類型。

傳回值

忽略值為None的元素，返回List中最大的元素，若集合元素全部為None則返回None。

樣本

{
  "Fn::Max": ["123","234"]
}

樣本返回

"234"

Fn::First

返回列表中第一個元素。

聲明

{  "Fn::First": "aList"}

參數

aList：一個含有元素的List；List中元素類型不限。

傳回值

輸出為集合中迭代返回的第一個元素；對loop來說，按照Items中迭代返回的Item產生的task execution id進行排序。

樣本

{
  "Fn::First": ["123","234"]
}

樣本返回

"123"

Fn::Last

返回列表中最後一個元素。

聲明

{"Fn::Last": "aList"}

參數

aList：一個含有元素的List；List中元素類型不限。

傳回值

輸出為集合中迭代返回的最後一個元素；對loop來說，按照Items中迭代返回的Item產生的task execution id進行排序。

樣本

{
  "Fn::Last": ["123","234"]
}

樣本返回

"234"

Fn::ListJoin

將多個參數轉換成列表。

聲明

{"Fn::ListJoin": "IterableContainer"}

參數

IterableContainer是一個可迭代的集合，集合中元素類型不限。

傳回值

將集合轉換成List輸出。

樣本

{"Fn::ListJoin": ["a",2, 3]}

樣本返回

["a",2,3]

Fn::Equals

比較兩個值是否相等。如果兩個值相等，則返回true；如果不相等，則返回false。

聲明

{  "Fn::Equals": ["parameter1", "parameter2"]}

參數

parameter1，parameter2為兩個任意類型值。

傳回值

如果兩個值相等，則返回true；如果不相等，則返回false。

樣本

{  "Fn::Equals": ["Running","Stopped"]}

樣本返回

false

Fn::If

如果指定的條件計算為true，則返回一個值；如果指定的條件計算為false，則返回另一個值。

聲明

{
  "Fn::If": [
    "condition",
    "value_if_true",
    "value_if_false"
  ]
}

參數

condition_name：待判斷的條件參數。
value_if_true：當指定的條件計算為true時，返回此值。
value_if_false：當指定的條件計算為false時，返回此值。

傳回值

當條件計算為true時，返回value_if_true。

當條件計算為false時，返回value_if_false。

樣本

{"Fn::If": [false,"Stopped","Running"]}

樣本返回

"Running"

Fn::Or

邏輯或操作。

聲明

{"Fn::Or": ["condition1","condition2"]}

參數

condition1、condition2：將進行邏輯或的條件。

傳回值

當condition1和condition2均為false時，返回false；否則，返回true。

樣本

{"Fn::Or": [true,false]}

樣本返回

true

Fn::And

邏輯或操作。

聲明

{"Fn::And": [ "condition1", "condition2"]}

參數

condition1、condition2：將要進行邏輯與的條件。

傳回值

當condition1和condition2均為true時，返回true；否則，返回false。

樣本

{"Fn::And": [true,false]}

樣本返回

false

Fn::Not

對值取否操作。

聲明

{"Fn::Not": "condition"}

參數

condition：將要取否的條件。

傳回值

當condition為true時，返回false；當condition為false時，返回true。

樣本

{"Fn::Not": true}

樣本返回

false

Fn::AddHour

表示對一個UTCT時間向後推移N小時，使其成為一個新的UTC時間。

聲明

{"Fn::AddHour": ["utc_time", "hours_count"  ]}

參數

utc_time：一個要向後推移的UTC時間。
hours_count：要向後推移的小時數，限取整數。

傳回值

utc_time被推移hours_count小時後的新UTC時間。

樣本

{  "Fn::AddHour": ["2019-06-01T02:12:45Z", 6]}

樣本返回

"2019-06-01T08:12:45Z"

Fn::FormatUTCTime

表示對一個UTC時間按不同單位精度進行格式化，產生的新時間其精度只保留到需要的時間單位。

聲明

Fn::FormatUTCTime: ["utc_time", "to_be_utc_time_format"]

參數

utc_time：待被格式化的UTC時間。
to_be_utc_time_format：將要把utc_time格式化成的新時間格式。

傳回值

新格式的時間。

樣本

{  "Fn::FormatUTCTime": ["2019-06-01T02:12:45Z","%Y-%m-%dT%H:%MZ"]}

樣本返回

"2019-06-01T02:12Z"

Fn::Eval

表示執行一個字串中的運算式（不支援運算式中含換行），並返回執行結果。聲明

{
  "Fn::Eval": [
    "expression"
  ]
}

參數

expression：被執行的運算式（如運算式）。

傳回值

運算式執行結果。

樣本

{  "Fn::Eval": ["1+3*2+3%2+1"]}

樣本返回

Fn::CalculateTimeByOpsWindow

表示您指定了24h中的一個時間段後，Fn::CalculateTimeByOpsWindow會根據函數的執行時間點，產生下一個在該時間段中的時間點。具體時間點產生規則為，當函數執行的時間點恰好在當天的時間段中時，產生的時間點將是函數執行時間+1min對應的時間點；當函數執行的時間點不在當天時間段中，且早於當天時間段的開始時間，則產生的時間點將是函數執行的當天時間段中的某個隨機時間點；當函數執行的時間點不在當天時間段中，且晚於當天時間段的結束時間，則產生的時間點將是函數執行當天的下一天對應時間段中的某個隨機時間點。

聲明

Fn::CalculateTimeByOpsWindow: [ "startTime", "endTime" ]

參數

startTime：24h中某時間段的開始時間（如01:00:00Z）。
endTime：24h中某時間段的結束時間（如03:00:00Z）。

傳回值

下一個在指定時間段中的UTC時間點字串。

樣本

{  "Fn::CalculateTimeByOpsWindow": ["01:00:00Z", "03:00:00Z"]}

樣本返回

"2019-09-24T01:01:00Z"

Fn::Jq

對JSON對象進行篩選，返回其中的某部分。

聲明

{  "Fn::Jq": [ "type", "jqSelector", "jsonObject" ]}

參數

type：可選"First"或"All"，其中First表示只返回第一個結果，All表示返回所有結果。
jqSelector：jq篩選語句，詳細可參考使用jq。
jsonObject：被篩選的JSON對象。

傳回值

JSON對象經jq運算式篩選後返回的結果。

樣本1

{
  "Fn::Jq": [
    "First",".PrivateIpAddress.IpAddress",
{
  "PrivateIpAddress": {
    "IpAddress": [
      "192.168.1.123", "192.168.1.234"
    ]
  },
  "VpcId": "vpc-xzxbamns",
  "VSwitchId": "vsw-zxcdsa"
}
}

樣本1返回

"192.168.1.123"

樣本2

{
  "Fn::Jq": [
    "All",".PrivateIpAddress.IpAddress",
{
  "PrivateIpAddress": {
    "IpAddress": [
      "192.168.1.123", "192.168.1.234"
    ]
  },
  "VpcId": "vpc-xzxbamns",
  "VSwitchId": "vsw-zxcdsa"
}
}

樣本2返回

["192.168.1.123", "192.168.1.234"]

Fn::Intersection

對多個數組取交集，返回共同包含的值。

聲明

{  "Fn::Intersection": [ list1, list2]}

參數

list1、list2：要取交集的數組。

傳回值

一個數組，其中的元素是多個數組共同包含的值。

樣本

{  "Fn::Intersection": [["i-1","i-2"],["i-1","i-3"]]}

樣本返回

["i-1"]

Fn::Union

對多個數組中的元素去重後合并為一個數組，返回合并後的新數組。

聲明

{  "Fn::Union": [ list1, list2]}

參數

list1、list2：要合并的數組。

傳回值

一個數組，其中的元素是多個數組的並集。

樣本

{
  "Fn::Union": [
    [
      "i-1",
      "i-2"
    ],
    [
      "i-1",
      "i-3"
    ]
  ]
}

樣本返回

["i-1","i-2","i-3"]

Fn::Difference

查看多個數組的並集與交集的差集，返回包含差集結果的新數組。

聲明

{  "Fn::Difference": [ list1, list2]}

參數

list1、list2：要篩選存在不同元素的數組。

傳回值

一個數組，其元素是多個數組的並集與交集的差集。

樣本

{
  "Fn::Difference": [
    ["i-1","i-2"],
    ["i-1"]]
}

樣本返回

["i-2"]

Fn::MapJoin

將兩個List組合成一個Map，組合時，會把第一個List內的所有值，作為Map中每個索引值對的鍵，會把第二個List內的值，作為Map中每個索引值對的值。

聲明

{'Fn::MapJoin': [List1, List2] }

參數

aListConatinsDicts：含有多個映射的List。

傳回值

一個Map，其中每個索引值對的鍵是List1的對應元素，每個索引值對的值是List2的對應元素。

樣本

{'Fn::MapJoin': [['i-1', 'i-2', 'i-3'], [1, 2, 3]] }

樣本返回

{'i-1': 1, 'i-2': 2, 'i-3': 3}

Fn::IsIpInCIDR

判斷指定的IP是否在指定的CIDR網段內。

聲明

{'Fn::IsIpInCIDR': [Ip, CIDR] }

參數

Ip、CIDR

傳回值

true or false

樣本1

{'Fn::IsIpInCIDR': ["10.0.1.159", "192.168.0.0/16"] }

樣本1返回

false

樣本2

{'Fn::IsIpInCIDR': ["192.168.255.0", "192.168.0.0/16"] }

樣本2返回

true

Fn::Sub

將輸入字串中的變數替換為指定的值。

聲明

{'Fn::Sub': [TargetString, JSON]}

參數

TargetString、JSON

傳回值

String

樣本

{
    "Fn::Sub": [
        "Var1: ${Var1}, Var2: ${Var2}",
        {
            "Var1": "Var1Value",
            "Var2": "Var2Value"
        }
    ]
}

樣本返回

"Var1: Var1Value, Var2: Var2Value"

Fn::DurationBetween

返回兩個時間點之間的時間長度。

聲明

{'Fn::DurationBetween': [DateTime_1, DateTime_2]}

參數

DateTime_1、DateTime_2

傳回值

String

樣本

{
    "Fn::DurationBetween": [
        "12:00:00",
        "13:00:00"
    ]
}

樣本返回

PT3600S

Fn::Escape

逸出字元串。

聲明

{'Fn::Escape': [String, ShellType] }

參數

String、ShellType

說明

ShellType目前僅支援PowerShell

傳回值

String

樣本

{
    "Fn::Escape": [
        '{"ACS:File":{"Collection":"Enabled","Filters":"[{\\"Path\\": \\"/home/admin/test\\",\\"Pattern\\":[\\"*\\"],\\"Recursive\\":false}]"},"ACS:Application":{"Collection":"Enabled"}, "ACS:Network":{"Collection":"Enabled"}}',
        'PowerShell'
    ]
}

樣本返回

'{\\"ACS:File\\":{\\"Collection\\":\\"Enabled\\",\\"Filters\\":\\"[{\\\\\\"Path\\\\\\": \\\\\\"/home/admin/test\\\\\\",\\\\\\"Pattern\\\\\\":[\\\\\\"*\\\\\\"],\\\\\\"Recursive\\\\\\":false}]\\"},\\"ACS:Application\\":{\\"Collection\\":\\"Enabled\\"}, \\"ACS:Network\\":{\\"Collection\\":\\"Enabled\\"}}'

Fn::ConvertMapToList

轉化JSON對象為Key、Value格式的列表。

聲明

{'Fn::ConvertMapToList': [JSON/JSONString] }

參數

JSON

傳回值

List

樣本1

{
    "Fn::ConvertMapToList": [
        {
            "key1": "value1",
            "key2": "value2"
        }
    ]
}

樣本1返回

[
  {
    "Key": "key1",
    "Value": "value1"
  },
  {
    "Key": "key2",
    "Value": "value2"
  }
]

樣本2

{
    "Fn::ConvertMapToList": [
        "{\"key1\": \"value1\", \"key2\": \"value2\"}"
    ]
}

樣本2返回

[
  {
    "Key": "key1",
    "Value": "value1"
  },
  {
    "Key": "key2",
    "Value": "value2"
  }
]