OOS provides multiple built-in functions that you can use when defining conditions, task properties, or template outputs. These functions help you process template parameters and output results more conveniently.
Functions
Built-in function name | Description |
Returns the Base64-encoded format of a string. | |
Returns the Base64-decoded result of a string. | |
Merges multiple maps into a list with maps as elements. | |
Merges multiple maps in a list into a single map. | |
Combines a set of strings into a single string that is separated by a delimiter. | |
Returns a single data element from a data element container by querying the index. | |
Splits a string into multiple values by using a delimiter. | |
Replaces a substring in a string with another substring. | |
Returns the smallest element in a list. | |
Returns the largest element in a list. | |
Returns the first element in a list. | |
Returns the last element in a list. | |
Converts multiple parameters into a list. | |
Compares two values to check whether they are equal. | |
Returns different values based on the condition evaluation. | |
Performs a logical NOT operation on a value. | |
Adds N hours to a UTC time. | |
Formats UTC time with different precision units. | |
Executes a single-line expression in a string and returns the result. | |
When a time window is specified, this function generates the next time point within the window based on the function execution time. | |
Logical AND. | |
Logical OR. | |
Returns the intersection of multiple arrays. | |
Returns the union of multiple arrays. | |
Returns the difference between the union and intersection of multiple arrays. | |
Filters JSON objects to obtain target property values. | |
Combines two lists into a map, using values from the first list as keys and values from the second list as values in each key-value pair of the map. | |
Determines whether a specified IP address is within a specified CIDR block. | |
Replaces variables in an input string with specified values. | |
Returns the duration between two time points. | |
Escapes a string. | |
Converts a JSON object into a list in Key-Value format. |
Scenarios
Built-in functions are primarily used in defining conditions, template tasks, or template outputs to process task outputs, referenced parameters, or user-defined values to achieve desired results. Here are some examples:
When defining conditions, the built-in function
Fn::Equalsis used.Conditions: NewTemporaryEcs: Fn::Equals: - '{{ buildType }}' - NewTemporaryEcsTask:
When setting the
WhenorPropertiesattributes in a task, the built-in functionFn::Equalsis used.FormatVersion: OOS-2019-06-01 Description: Execute a single API Tasks: - Name: ExecuteApi Action: ACS::ExecuteApi When: Fn::Equals: - '{{ param }}' - true Description: en: Perform a single ExecuteApi operation. zh-cn: Execute API Properties: Service: ecs API: DescribeRegions Parameters: InstanceChargeType: Fn::Equals: - 1 - 1 ResourceType: ''Template output values can also be processed using built-in functions according to your needs.
Outputs: invocationOutput: Type: String Value: 'Fn::Base64Decode': '{{ describeInvocationResults.invocationResult }}'
Examples of built-in functions
The use of built-in functions mainly consists of the function name and parameters to be processed. The function declaration expression represents the result after the function processes the parameters, and the expression can be referenced like other parameters as the function's return value.
Fn::Base64Encode
Returns the Base64-encoded format of a string.
Declaration
{"Fn::Base64Encode": "StringToBeBase64"} Parameters
StringToBeBase64: The string to be Base64 encoded.
Return Value
The original string represented in Base64 format.
Example
{"Fn::Base64Encode": "hello"} Example Return
"aGVsbG8="Fn::Base64Decode
Returns the decoded result of a Base64 string.
Declaration
{"Fn::Base64Decode": "Base64ToBeString"}Parameters
Base64ToBeString: A string represented in Base64 encoding.
Return Value
The original string after Base64 decoding.
Example
{"Fn::Base64Decode": "aGVsbG8="} Example Return
"hello"Fn::MergeMapToList
Merges multiple maps into a list with maps as elements.
Declaration
{"Fn::MergeMapToList": "aListConatinsDicts"}Parameters
aListConatinsDicts: A list containing multiple maps.
Return Value
A list with maps as elements.
Example 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"
]
}
]
}Example 1 Return
[
{
"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"
}
]Example 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"
]
}
]
}Example 2 Return
[
{
"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
Merges multiple maps in a list into a single map.
Declaration
{ "Fn::MergeMap": "aListConatinsDicts"}Parameters
aListConatinsDicts: A list containing multiple maps.
Return Value
A single map merged from multiple maps in the list.
Example
{
"Fn::MergeMap": [
{
"key_1": "value_1"
},
{
"key_2": "value_2"
}
]
}Example Return
{"key_1": "value_1","key_2": "value_2"}Fn::Join
Combines a set of strings into a single string that is separated by a delimiter.
Declaration
{"Fn::Join": ["Connector","aListContainsString"]} Parameters
Connector: A string used as the connector.
aListContainsString: A list containing strings.
Return Value
A string that combines multiple elements in the list.
Example
{
"Fn::Join": [
",",
[
"a",
"b",
"c"
]
]
}Example Return
"a,b,c"Fn::Select
Returns a single data element from a data element container by querying the index.
Declaration
{"Fn::Select": ["Index","Container"]}Parameters
Index: A string or number representing the index of the queried container.
Container: The list or map being queried.
Return Value
The result returned by querying the specified index.
Example 1
{
"Fn::Select": [
"IpAddress",
{
"IpAddress": [
"192.168.1.123",
"192.168.1.234"
]
}
]
}Example 1 Return
["192.168.1.123","192.168.1.234"]Example 2
{
"Fn::Select": [
"1",
[
"192.168.1.123",
"192.168.1.234"
]
]
}Example 2 Return
"192.168.1.234"Fn::Split
Splits a string into multiple values by using a delimiter.
Declaration
{"Fn::Split": ["Separator","StringToSeprate"]}Parameters
Separator: A string used as the separator.
StringToSeparate: A string that will be split into a list based on the separator.
Return Value
A list created by splitting StringToSeparate using the separator.
Example
{
"Fn:: Split": [",","a,b,c"]
}Example Return
[
"a",
"b",
"c"
]Fn::Replace
Replaces a substring in a string with another substring.
Declaration
{ "Fn::Replace": [{"$varName": "StringToReplaceWith"}, "StringToReplace"]}Parameters
$varName: A placeholder that starts with $ followed by a regular parameter name. The parameter name after $ must follow the same naming requirements as template parameter names.
StringToReplaceWith: The value that will replace the placeholder.
StringToReplace: The value to be replaced (containing placeholders), such as "$varName is foo".
Return Value
If the parameter StringToReplaceWith is "baz", then the return value would be "baz is foo".
Example
{ "Fn::Replace": [{"$varName": "baz"}, "$varName is foo" ]}Example Return
"baz is foo"Fn::Min
Returns the smallest element in a list.
Declaration
{"Fn::Min": "aList"}Parameters
aList: A list containing elements. The elements in the list can be strings, integers, datetime objects, or None, but they must all be of the same type.
Return Value
Returns the smallest element in the list, ignoring elements with a value of None. If all elements in the collection are None, returns None.
Example
{
"Fn::Min": ["123","234"]
}Example Return
"123"Fn::Max
Returns the largest element in a list.
Declaration
{"Fn::Max": "aList"}Parameters
aList: A list containing elements. The elements in the list can be strings, integers, datetime objects, or None, but they must all be of the same type.
Return Value
Returns the largest element in the list, ignoring elements with a value of None. If all elements in the collection are None, returns None.
Example
{
"Fn::Max": ["123","234"]
}Example Return
"234"Fn::First
Returns the first element in a list.
Declaration
{ "Fn::First": "aList"}Parameters
aList: A list containing elements. The element types in the list are not restricted.
Return Value
Returns the first element from the collection during iteration. For loops, it sorts by the task execution ID generated from the Items being iterated.
Example
{
"Fn::First": ["123","234"]
}Example Return
"123"Fn::Last
Returns the last element in a list.
Declaration
{"Fn::Last": "aList"}Parameters
aList: A list containing elements. The element types in the list are not restricted.
Return Value
Returns the last element from the collection during iteration. For loops, it sorts by the task execution ID generated from the Items being iterated.
Example
{
"Fn::Last": ["123","234"]
}Example Return
"234"Fn::ListJoin
Converts multiple parameters into a list.
Declaration
{"Fn::ListJoin": "IterableContainer"}Parameters
IterableContainer is an iterable collection. The element types in the collection are not restricted.
Return Value
Converts the collection into a list and outputs it.
Example
{"Fn::ListJoin": ["a",2, 3]}Example Return
["a",2,3]Fn::Equals
Compares two values to check whether they are equal. If the two values are equal, returns true. If not, returns false.
Declaration
{ "Fn::Equals": ["parameter1", "parameter2"]}Parameters
parameter1, parameter2: Two values of any type.
Return Value
If the two values are equal, returns true. If not, returns false.
Example
{ "Fn::Equals": ["Running","Stopped"]}Example Return
falseFn::If
Returns one of two possible values. The function returns one value if a specified condition is evaluated to true, and returns the other value if not.
Declaration
{
"Fn::If": [
"condition",
"value_if_true",
"value_if_false"
]
}Parameters
condition_name: The condition parameter to be evaluated.
value_if_true: The value to return when the specified condition evaluates to true.
value_if_false: The value to return when the specified condition evaluates to false.
Return Value
When the condition evaluates to true, returns value_if_true.
When the condition evaluates to false, returns value_if_false.
Example
{"Fn::If": [false,"Stopped","Running"]}Example Return
"Running"Fn::Or
Logical OR operation.
Declaration
{"Fn::Or": ["condition1","condition2"]}Parameters
condition1, condition2: Conditions for the logical OR operation.
Return Value
When both condition1 and condition2 are false, returns false. Otherwise, returns true.
Example
{"Fn::Or": [true,false]}Example Return
trueFn::And
Logical AND operation.
Declaration
{"Fn::And": [ "condition1", "condition2"]}Parameters
condition1, condition2: Conditions for the logical AND operation.
Return Value
When both condition1 and condition2 are true, returns true. Otherwise, returns false.
Example
{"Fn::And": [true,false]}Example Return
falseFn::Not
Performs a logical NOT operation on a value.
Declaration
{"Fn::Not": "condition"}Parameters
condition: The condition to be negated.
Return Value
When condition is true, returns false. When condition is false, returns true.
Example
{"Fn::Not": true}Example Return
falseFn::AddHour
Adds N hours to a UTC time to create a new UTC time.
Declaration
{"Fn::AddHour": ["utc_time", "hours_count" ]}Parameters
utc_time: A UTC time to which hours will be added.
hours_count: The number of hours to add, must be an integer.
Return Value
A new UTC time after adding hours_count hours to utc_time.
Example
{ "Fn::AddHour": ["2019-06-01T02:12:45Z", 6]}Example Return
"2019-06-01T08:12:45Z"Fn::FormatUTCTime
Formats a UTC time with different precision units, generating a new time that preserves precision only up to the required time unit.
Declaration
Fn::FormatUTCTime: ["utc_time", "to_be_utc_time_format"] Parameters
utc_time: The UTC time to be formatted.
to_be_utc_time_format: The new time format to which utc_time will be formatted.
Return Value
The time in the new format.
Example
{ "Fn::FormatUTCTime": ["2019-06-01T02:12:45Z","%Y-%m-%dT%H:%MZ"]}Example Return
"2019-06-01T02:12Z"Fn::Eval
Executes an expression in a string (expressions with line breaks are not supported) and returns the result. Declaration
{
"Fn::Eval": [
"expression"
]
}Parameters
expression: The expression to be executed (such as an arithmetic expression).
Return Value
The result of executing the expression.
Example
{ "Fn::Eval": ["1+3*2+3%2+1"]}Example Return
9Fn::CalculateTimeByOpsWindow
When you specify a time window within a 24-hour period, Fn::CalculateTimeByOpsWindow generates the next time point within that window based on the function's execution time. Specifically, if the function execution time happens to be within the day's time window, the generated time point will be the function execution time + 1 minute. If the function execution time is outside the day's time window and earlier than the window's start time, the generated time point will be a random time within that day's time window. If the function execution time is outside the day's time window and later than the window's end time, the generated time point will be a random time within the next day's corresponding time window.
Declaration
Fn::CalculateTimeByOpsWindow: [ "startTime", "endTime" ]Parameters
startTime: The start time of a time window within a 24-hour period (such as 01:00:00Z).
endTime: The end time of a time window within a 24-hour period (such as 03:00:00Z).
Return Value
A string representing the next UTC time point within the specified time window.
Example
{ "Fn::CalculateTimeByOpsWindow": ["01:00:00Z", "03:00:00Z"]}Example Return
"2019-09-24T01:01:00Z"Fn::Jq
Filters JSON objects to obtain target property values.
Declaration
{ "Fn::Jq": [ "type", "jqSelector", "jsonObject" ]} Parameters
type: Can be either "First" or "All". "First" returns only the first result, while "All" returns all results.
jqSelector: A jq filtering statement. For more information, see Using jq.
jsonObject: The JSON object to be filtered.
Return Value
The result returned after filtering the JSON object with the jq expression.
Example 1
{
"Fn::Jq": [
"First",".PrivateIpAddress.IpAddress",
{
"PrivateIpAddress": {
"IpAddress": [
"192.168.1.123", "192.168.1.234"
]
},
"VpcId": "vpc-xzxbamns",
"VSwitchId": "vsw-zxcdsa"
}
}Example 1 Return
"192.168.1.123"Example 2
{
"Fn::Jq": [
"All",".PrivateIpAddress.IpAddress",
{
"PrivateIpAddress": {
"IpAddress": [
"192.168.1.123", "192.168.1.234"
]
},
"VpcId": "vpc-xzxbamns",
"VSwitchId": "vsw-zxcdsa"
}
}Example 2 Return
["192.168.1.123", "192.168.1.234"]Fn::Intersection
Returns the intersection of multiple arrays, containing the values that are common to all arrays.
Declaration
{ "Fn::Intersection": [ list1, list2]} Parameters
list1, list2: Arrays for which to find the intersection.
Return Value
An array containing elements that are common to all the input arrays.
Example
{ "Fn::Intersection": [["i-1","i-2"],["i-1","i-3"]]}Example Return
["i-1"]Fn::Union
Merges multiple arrays into a single array after removing duplicates, returning the new merged array.
Declaration
{ "Fn::Union": [ list1, list2]} Parameters
list1, list2: Arrays to be merged.
Return Value
An array containing the union of elements from multiple arrays.
Example
{
"Fn::Union": [
[
"i-1",
"i-2"
],
[
"i-1",
"i-3"
]
]
}Example Return
["i-1","i-2","i-3"]Fn::Difference
Returns the difference between the union and intersection of multiple arrays in a new array.
Declaration
{ "Fn::Difference": [ list1, list2]} Parameters
list1, list2: Arrays to find elements that differ.
Return Value
An array containing elements that are in the union but not in the intersection of multiple arrays.
Example
{
"Fn::Difference": [
["i-1","i-2"],
["i-1"]]
}Example Return
["i-2"]Fn::MapJoin
Combines two lists into a map, using values from the first list as keys and values from the second list as values in each key-value pair of the map.
Declaration
{'Fn::MapJoin': [List1, List2] } Parameters
aListConatinsDicts: A list containing multiple maps.
Return Value
A map where each key-value pair has a key from List1 and a corresponding value from List2.
Example
{'Fn::MapJoin': [['i-1', 'i-2', 'i-3'], [1, 2, 3]] } Example Return
{'i-1': 1, 'i-2': 2, 'i-3': 3}Fn::IsIpInCIDR
Determines whether a specified IP address is within a specified CIDR block.
Declaration
{'Fn::IsIpInCIDR': [Ip, CIDR] } Parameters
Ip, CIDR
Return Value
true or false
Example 1
{'Fn::IsIpInCIDR': ["10.0.1.159", "192.168.0.0/16"] } Example 1 Return
falseExample 2
{'Fn::IsIpInCIDR': ["192.168.255.0", "192.168.0.0/16"] } Example 2 Return
trueFn::Sub
Replaces variables in an input string with specified values.
Declaration
{'Fn::Sub': [TargetString, JSON]} Parameters
TargetString, JSON
Return Value
String
Example
{
"Fn::Sub": [
"Var1: ${Var1}, Var2: ${Var2}",
{
"Var1": "Var1Value",
"Var2": "Var2Value"
}
]
}Example Return
"Var1: Var1Value, Var2: Var2Value"Fn::DurationBetween
Returns the duration between two time points.
Declaration
{'Fn::DurationBetween': [DateTime_1, DateTime_2]} Parameters
DateTime_1, DateTime_2
Return Value
String
Example
{
"Fn::DurationBetween": [
"12:00:00",
"13:00:00"
]
}Example Return
PT3600SFn::Escape
Escapes a string.
Declaration
{'Fn::Escape': [String, ShellType] } Parameters
String, ShellType
ShellType currently only supports PowerShell
Return Value
String
Example
{
"Fn::Escape": [
'{"ACS:File":{"Collection":"Enabled","Filters":"[{\\"Path\\": \\"/home/admin/test\\",\\"Pattern\\":[\\"*\\"],\\"Recursive\\":false}]"},"ACS:Application":{"Collection":"Enabled"}, "ACS:Network":{"Collection":"Enabled"}}',
'PowerShell'
]
}Example Return
'{\\"ACS:File\\":{\\"Collection\\":\\"Enabled\\",\\"Filters\\":\\"[{\\\\\\"Path\\\\\\": \\\\\\"/home/admin/test\\\\\\",\\\\\\"Pattern\\\\\\":[\\\\\\"*\\\\\\"],\\\\\\"Recursive\\\\\\":false}]\\"},\\"ACS:Application\\":{\\"Collection\\":\\"Enabled\\"}, \\"ACS:Network\\":{\\"Collection\\":\\"Enabled\\"}}'Fn::ConvertMapToList
Converts a JSON object into a list in Key-Value format.
Declaration
{'Fn::ConvertMapToList': [JSON/JSONString] } Parameters
JSON
Return Value
List
Example 1
{
"Fn::ConvertMapToList": [
{
"key1": "value1",
"key2": "value2"
}
]
}Example 1 Return
[
{
"Key": "key1",
"Value": "value1"
},
{
"Key": "key2",
"Value": "value2"
}
]Example 2
{
"Fn::ConvertMapToList": [
"{\"key1\": \"value1\", \"key2\": \"value2\"}"
]
}Example 2 Return
[
{
"Key": "key1",
"Value": "value1"
},
{
"Key": "key2",
"Value": "value2"
}
]