Bicep 的字串函式

  • 發行項

本文說明用來處理字串的 Bicep 函式。

base64

base64(inputString)

傳回輸入字串的 base64 表示法。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
inputString Yes string 要以 base64 表示法傳回的值。

傳回值

字串，包含 base64 表示法。

範例

下列範例顯示如何使用 base64 函式。

param stringData string = 'one, two, three'
param jsonFormattedData string = '{\'one\': \'a\', \'two\': \'b\'}'

var base64String = base64(stringData)
var base64Object = base64(jsonFormattedData)

output base64Output string = base64String
output toStringOutput string = base64ToString(base64String)
output toJsonOutput object = base64ToJson(base64Object)

上述範例中具有預設值的輸出如下：

名稱 類型 值
base64Output String b25lLCB0d28sIHRocmVl
toStringOutput String one, two, three
toJsonOutput Object {"one": "a", "two": "b"}

base64ToJson

base64ToJson(base64Value)

將 base64 表示法轉換為 JSON 物件。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
base64Value Yes string 要轉換為 JSON 物件的 base64 表示法。

傳回值

JSON 物件。

範例

下列範例會使用 base64ToJson 函式來轉換 base64 值︰

param stringData string = 'one, two, three'
param jsonFormattedData string = '{\'one\': \'a\', \'two\': \'b\'}'

var base64String = base64(stringData)
var base64Object = base64(jsonFormattedData)

output base64Output string = base64String
output toStringOutput string = base64ToString(base64String)
output toJsonOutput object = base64ToJson(base64Object)

上述範例中具有預設值的輸出如下：

名稱 類型 值
base64Output String b25lLCB0d28sIHRocmVl
toStringOutput String one, two, three
toJsonOutput Object {"one": "a", "two": "b"}

base64ToString

base64ToString(base64Value)

將 base64 表示法轉換為字串。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
base64Value Yes string 要轉換為字串的 base64 表示法。

傳回值

轉換後之 base64 值的字串。

範例

下列範例會使用 base64ToString 函式來轉換 base64 值︰

param stringData string = 'one, two, three'
param jsonFormattedData string = '{\'one\': \'a\', \'two\': \'b\'}'

var base64String = base64(stringData)
var base64Object = base64(jsonFormattedData)

output base64Output string = base64String
output toStringOutput string = base64ToString(base64String)
output toJsonOutput object = base64ToJson(base64Object)

上述範例中具有預設值的輸出如下：

名稱 類型 值
base64Output String b25lLCB0d28sIHRocmVl
toStringOutput String one, two, three
toJsonOutput Object {"one": "a", "two": "b"}

concat

concat(arg1, arg2, arg3, ...)

結合多個字串值並傳回串連字串，或結合多個陣列並傳回串連陣列。 若要改善可讀性，請使用字串插補，而不是使用 concat() 函式。 不過，在某些情況下，例如多行字串中的字串取代，您可能需要使用 concat() 函式或 replace() 函式進行回復。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
arg1 Yes 字串或陣列 串連的第一個字串或陣列。
更多引數 No 字串或陣列 串連的其他字串或陣列 (循序順序)。

此函式可以接受任意數目的引數，並且可針對參數接受字串或陣列。 但您無法為參數提供陣列和字串。 字串只能與其他字串串連。

傳回值

串連值的字串或陣列。

範例

下列範例示範使用插補與使用 concat() 函式之間的比較。 這兩個輸出會傳回相同的值。

param prefix string = 'prefix'

output concatOutput string = concat(prefix, 'And', uniqueString(resourceGroup().id))
output interpolationOutput string = '${prefix}And${uniqueString(resourceGroup().id)}'

上述範例中具有預設值的輸出如下：

名稱 類型 值
concatOutput String prefixAnd5yj4yjf5mbg72
interpolationOutput String prefixAnd5yj4yjf5mbg72

多行字串目前不支援插補。 下列範例示範使用插補與使用 concat() 函式之間的比較。

var blocked = 'BLOCKED'

output concatOutput string = concat('''interpolation
is ''', blocked)
output interpolationOutput string = '''interpolation
is ${blocked}'''

上述範例中具有預設值的輸出如下：

名稱 類型 值
concatOutput String interpolation\nis BLOCKED
interpolationOutput String interpolation\nis ${blocked}

contains

contains(container, itemToFind)

檢查陣列中是否包含值、物件中是否包含索引鍵，或字串中是否包含子字串。 字串比較會區分大小寫。 不過，測試時，如果物件包含索引鍵，比較便不區分大小寫。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
容器 Yes 陣列、物件或字串 其中包含要尋找之值的值。
itemToFind Yes 字串或整數 要尋找的值。

傳回值

找到項目則傳回 True，否則會傳回 False。

範例

下列範例顯示如何使用不同類型的 contains：

param stringToTest string = 'OneTwoThree'
param objectToTest object = {
  one: 'a'
  two: 'b'
  three: 'c'
}
param arrayToTest array = [
  'one'
  'two'
  'three'
]

output stringTrue bool = contains(stringToTest, 'e')
output stringFalse bool = contains(stringToTest, 'z')
output objectTrue bool = contains(objectToTest, 'one')
output objectFalse bool = contains(objectToTest, 'a')
output arrayTrue bool = contains(arrayToTest, 'three')
output arrayFalse bool = contains(arrayToTest, 'four')

上述範例中具有預設值的輸出如下：

名稱 類型 值
stringTrue Bool True
stringFalse Bool False
objectTrue Bool True
objectFalse Bool False
arrayTrue Bool True
arrayFalse Bool False

dataUri

dataUri(stringToConvert)

將值轉換為資料 URI。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
stringToConvert Yes string 要轉換為資料 URI 的值。

傳回值

格式化為資料 URI 的字串。

範例

下列範例會將值轉換為資料 URI，並將資料 URI 轉換為字串︰

param stringToTest string = 'Hello'
param dataFormattedString string = 'data:;base64,SGVsbG8sIFdvcmxkIQ=='

output dataUriOutput string = dataUri(stringToTest)
output toStringOutput string = dataUriToString(dataFormattedString)

上述範例中具有預設值的輸出如下：

名稱 類型 值
dataUriOutput String data:text/plain;charset=utf8;base64,SGVsbG8=
toStringOutput String Hello, World!

dataUriToString

dataUriToString(dataUriToConvert)

將資料 URI 格式化值轉換為字串。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
dataUriToConvert Yes string 要轉換的資料 URI 值。

傳回值

字串，包含已轉換的值。

範例

下列範例會將值轉換為資料 URI，並將資料 URI 轉換為字串︰

param stringToTest string = 'Hello'
param dataFormattedString string = 'data:;base64,SGVsbG8sIFdvcmxkIQ=='

output dataUriOutput string = dataUri(stringToTest)
output toStringOutput string = dataUriToString(dataFormattedString)

上述範例中具有預設值的輸出如下：

名稱 類型 值
dataUriOutput String data:text/plain;charset=utf8;base64,SGVsbG8=
toStringOutput String Hello, World!

empty

empty(itemToTest)

判斷陣列、物件或字串是否空白。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
itemToTest Yes 陣列、物件或字串 檢查其是否為空白的值。

傳回值

如果值空白則傳回 True，否則會傳回 False。

範例

下列範例會檢查陣列、物件和字串是否空白。

param testArray array = []
param testObject object = {}
param testString string = ''

output arrayEmpty bool = empty(testArray)
output objectEmpty bool = empty(testObject)
output stringEmpty bool = empty(testString)

上述範例中具有預設值的輸出如下：

名稱 類型 值
arrayEmpty Bool True
objectEmpty Bool True
stringEmpty Bool True

endsWith

endsWith(stringToSearch, stringToFind)

判斷字串結尾是否為值。 此比較不區分大小寫。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
stringToSearch Yes string 其中包含要尋找之項目的值。
stringToFind Yes string 要尋找的值。

傳回值

如果最後一個字元或字串字元與該值相符，則傳回 True；否則會傳回 False。

範例

下列範例顯示如何使用 startsWith 和 endsWith 函式：

output startsTrue bool = startsWith('abcdef', 'ab')
output startsCapTrue bool = startsWith('abcdef', 'A')
output startsFalse bool = startsWith('abcdef', 'e')
output endsTrue bool = endsWith('abcdef', 'ef')
output endsCapTrue bool = endsWith('abcdef', 'F')
output endsFalse bool = endsWith('abcdef', 'e')

上述範例中具有預設值的輸出如下：

名稱 類型 值
startsTrue Bool True
startsCapTrue Bool True
startsFalse Bool False
endsTrue Bool True
endsCapTrue Bool True
endsFalse Bool False

第一

first(arg1)

傳回字串的第一個字元或陣列的第一個元素。 如果指定空字串，函式會產生空字串。 如果是空陣列，函式會傳回 null。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
arg1 Yes 陣列或字串 要擷取其第一個元素或字元的值。

傳回值

陣列中第一個字元的字串或第一個元素的類型 (字串、整數、陣列或物件)。

範例

下列範例顯示如何搭配使用 first 函式與陣列和字串。

param arrayToTest array = [
  'one'
  'two'
  'three'
]

output arrayOutput string = first(arrayToTest)
output stringOutput string = first('One Two Three')

上述範例中具有預設值的輸出如下：

名稱 類型 值
arrayOutput String 一個
stringOutput String O

format

format(formatString, arg1, arg2, ...)

從輸入值建立格式化字串。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
formatString Yes string 複合格式字串。
arg1 Yes 字串、整數或布林值 要納入格式化字串的值。
其他引數 No 字串、整數或布林值 要納入格式化字串的其他值。

備註

使用此函式來格式化 Bicep 檔案中的字串。 此函式使用的格式化選項與 .NET 中的 System.String.Format 方法相同。

範例

下列範例說明如何使用 format 函式。

param greeting string = 'Hello'
param name string = 'User'
param numberToFormat int = 8175133
param objectToFormat object = { prop: 'value' }

output formatTest string = format('{0}, {1}. Formatted number: {2:N0}', greeting, name, numberToFormat)
output formatObject string = format('objectToFormat: {0}', objectToFormat)

上述範例中具有預設值的輸出如下：

名稱 類型 值
formatTest String Hello, User. Formatted number: 8,175,133
formatObject String objectToFormat: {'prop':'value'}

guid

guid(baseString, ...)

建立一個值，格式為根據提供作為參數之值的全域唯一識別碼。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
baseString Yes string 雜湊函式中用來建立 GUID 的值。
視需要，也會使用其他參數 No string 您可以視需要新增多個字串，來建立指定唯一性層級的值。

備註

當您需要建立格式為全域唯一識別碼的值時，此函式很有幫助。 您提供限制結果唯一性範圍的參數值。 您可以指定名稱對於訂用帳戶、資源群組或部署是否唯一。

傳回的值不是隨機字串，而是參數的雜湊函式結果。 傳回的值為 36 個字元長。 這不是全域唯一的值。 若要建立新的 GUID，而不是以參數的雜湊值為基礎，請使用 newGuid 函式。

注意

參數順序會影響傳回的值。 例如：

guid('hello', 'world') 和 guid('world', 'hello')

不會傳回相同的值。

下列範例顯示如何使用 guid 來建立常用層級的唯一值。

在訂用帳戶範圍內是唯一

guid(subscription().subscriptionId)

在資源群組範圍內是唯一

guid(resourceGroup().id)

在資源群組的部署範圍內是唯一

guid(resourceGroup().id, deployment().name)

guid 函式會根據 RFC 4122 §4.3 實作演算法。 原始來源可在 GuidUtility 中找到，其中有部分修改。

傳回值

字串，包含 36 個字元，格式為全域唯一識別碼。

範例

下列範例會傳回 guid 的結果：

output guidPerSubscription string = guid(subscription().subscriptionId)
output guidPerResourceGroup string = guid(resourceGroup().id)
output guidPerDeployment string = guid(resourceGroup().id, deployment().name)

indexOf

indexOf(stringToSearch, stringToFind)

傳回值在字串內的第一個位置。 此比較不區分大小寫。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
stringToSearch Yes string 其中包含要尋找之項目的值。
stringToFind Yes string 要尋找的值。

傳回值

整數，代表要尋找之項目的位置。 此值是以零為起始。 如果找不到該項目，則傳回 -1。

範例

下列範例顯示如何使用 indexOf 和 lastIndexOf 函式：

output firstT int = indexOf('test', 't')
output lastT int = lastIndexOf('test', 't')
output firstString int = indexOf('abcdef', 'CD')
output lastString int = lastIndexOf('abcdef', 'AB')
output notFound int = indexOf('abcdef', 'z')

上述範例中具有預設值的輸出如下：

名稱 類型 值
firstT int 0
lastT int 3
firstString int 2
lastString int 0
notFound int -1

join

join(inputArray, delimiter)

將字串陣列聯結成單一字串，並以分隔符號分隔。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
inputArray Yes 字串陣列。 要聯結的字串陣列。
分隔符號 Yes 用於分割字串的分隔符號。

傳回值

字串。

範例

下列範例會將輸入字串陣列聯結成以逗號或分號分隔的字串。

var arrayString = [
  'one'
  'two'
  'three'
]

output firstOutput string = join(arrayString, ',')
output secondOutput string = join(arrayString, ';')

上述範例中具有預設值的輸出如下：

名稱 類型 值
firstOutput String "one,two,three"
secondOutput String "one;two;three"

此函式需要 Bicep CLI 0.8.X 版或以上版本。

json

json(arg1)

將有效的 JSON 字串轉換成 JSON 資料類型。 如需詳細資訊，請參閱 json 函式。

命名空間：sys (部分機器翻譯)。

最後一

last(arg1)

傳回字串的最後一個字元或陣列的最後一個元素。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
arg1 Yes 陣列或字串 要擷取其最後一個元素或字元的值。

傳回值

陣列中最後一個字元的字串，或最後一個元素的類型 (字串、整數、陣列或物件)。

範例

下列範例顯示如何搭配使用 last 函式與陣列和字串。

param arrayToTest array = [
  'one'
  'two'
  'three'
]

output arrayOutput string = last(arrayToTest)
output stringOutput string = last('One Two Three')

上述範例中具有預設值的輸出如下：

名稱 類型 值
arrayOutput String 3
stringOutput String e

lastIndexOf

lastIndexOf(stringToSearch, stringToFind)

傳回值在字串內的最後一個位置。 此比較不區分大小寫。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
stringToSearch Yes string 其中包含要尋找之項目的值。
stringToFind Yes string 要尋找的值。

傳回值

整數，代表要尋找之項目的最後一個位置。 此值是以零為起始。 如果找不到該項目，則傳回 -1。

範例

下列範例說明如何使用 indexOf 和 lastIndexOf 函式：

output firstT int = indexOf('test', 't')
output lastT int = lastIndexOf('test', 't')
output firstString int = indexOf('abcdef', 'CD')
output lastString int = lastIndexOf('abcdef', 'AB')
output notFound int = indexOf('abcdef', 'z')

上述範例中具有預設值的輸出如下：

名稱 類型 值
firstT int 0
lastT int 3
firstString int 2
lastString int 0
notFound int -1

length

length(string)

傳回字串中的字元數、陣列中的元素數，或物件中根層級的屬性數。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
arg1 Yes 陣列、字串或物件 用於取得元素數目的陣列、用於取得字元數目的字串，或用於取得根層級屬性數目的物件。

傳回值

整數。

範例

下列範例顯示如何搭配使用 length 與陣列和字串：

param arrayToTest array = [
  'one'
  'two'
  'three'
]
param stringToTest string = 'One Two Three'
param objectToTest object = {
  propA: 'one'
  propB: 'two'
  propC: 'three'
  propD: {
    'propD-1': 'sub'
    'propD-2': 'sub'
  }
}

output arrayLength int = length(arrayToTest)
output stringLength int = length(stringToTest)
output objectLength int = length(objectToTest)

上述範例中具有預設值的輸出如下：

名稱 類型 值
arrayLength int 3
stringLength int 13
objectLength int 4

newGuid

newGuid()

以全域唯一識別碼格式傳回值。 此函數只能用於參數的預設值。

命名空間：sys (部分機器翻譯)。

備註

您只能在運算式內使用此函式，以取得參數的預設值。 在 Bicep 檔案中的其他地方使用此函式會傳回錯誤。 在 Bicep 檔案的其他部分不允許該函式，因為其會在每次呼叫時傳回不同的值。 使用相同的參數部署相同的 Bicep 檔案，並不會可靠地產生相同的結果。

NewGuid 函式與 guid 函式不同，因為前者不會採用任何參數。 當您使用相同的參數呼叫 guid 時，每次都會傳回相同的識別碼。 當您需要針對特定環境確實地產生相同的 GUID 時，請使用 guid。 當您每次需要不同的識別碼 (例如將資源部署至測試環境) 時，請使用 newGuid。

newGuid 函式會使用 .NET Framework 中的 Guid 結構，產生全域唯一識別碼。

如果您使用重新部署先前成功的部署選項，且先前的部署含有使用 newGuid 的參數，則不會重新評估該參數。 相反地，將會在復原部署中自動重複使用來自稍早部署的參數值。

在測試環境中，您可能需要重複部署只短時間存留的資源。 與其建構唯一名稱，您不如使用 newGuid 搭配 uniqueString 來建立唯一名稱。

重新部署相依於 newGuid 函式以取得預設值的 Bicep 檔案時，請謹慎小心。 當您重新部署且未提供參數的值時，會重新評估該函數。 如果您想更新現有的資源，而不是建立新的資源，請傳入來自先前部署的參數值。

傳回值

字串，包含 36 個字元，格式為全域唯一識別碼。

範例

下列範例顯示具有新識別碼的參數。

param guidValue string = newGuid()

output guidOutput string = guidValue

前述範例的輸出會隨著個別部署而有所不同，但會類似於：

名稱 類型 值
guidOutput string b76a51fc-bd72-4a77-b9a2-3c29e7d2e551

下列範例使用 newGuid 函式來建立儲存體帳戶的唯一名稱。 這個 Bicep 檔可能適用於儲存體帳戶已存在一段短時間且未重新部署的測試環境。

param guidValue string = newGuid()

var storageName = 'storage${uniqueString(guidValue)}'

resource myStorage 'Microsoft.Storage/storageAccounts@2018-07-01' = {
  name: storageName
  location: 'West US'
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {}
}

output nameOutput string = storageName

前述範例的輸出會隨著個別部署而有所不同，但會類似於：

名稱 類型 值
nameOutput string storagenziwvyru7uxie

padLeft

padLeft(valueToPad, totalLength, paddingCharacter)

藉由將字元新增至左邊，直到到達指定的總長度，以傳回靠右對齊的字串。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
valueToPad Yes 字串或整數 要靠右對齊的值。
totalLength Yes int 傳回字串中的字元總數。
paddingCharacter No 單一字元 要用於左側填補直到達到總長度的字元。 預設值是空格。

如果原始字串長度超過要填補的字元數，則不會新增任何字元。

傳回值

至少含有指定字元數的字串。

範例

下列範例顯示如何藉由新增「零」字元直到符合字元總數，以填補使用者提供的參數值。

param testString string = '123'

output stringOutput string = padLeft(testString, 10, '0')

上述範例中具有預設值的輸出如下：

名稱 類型 值
stringOutput String 0000000123

replace

replace(originalString, oldString, newString)

傳回具備由另一個字串取代的一個字串之所有執行個體的新字串。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
originalString Yes string 具備由另一個字串取代的一個字串之所有執行個體的值。
oldString Yes string 要從原始字串中移除的字串。
newString Yes string 要新增來取代移除之字串的字串。

傳回值

具有已取代字元的字串。

範例

下列範例會示範如何從使用者提供的字串中將所有的連字號移除，以及如何使用另一個字串來取代一部分的字串。

param testString string = '123-123-1234'

output firstOutput string = replace(testString, '-', '')
output secondOutput string = replace(testString, '1234', 'xxxx')

上述範例中具有預設值的輸出如下：

名稱 類型 值
firstOutput String 1231231234
secondOutput String 123-123-xxxx

skip

skip(originalValue, numberToSkip)

傳回位於指定字元數目之後的所有字元所組成的字串，或傳回位於指定元素數目之後的所有元素所形成的陣列。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
originalValue Yes 陣列或字串 要用於略過的陣列或字串。
numberToSkip Yes int 要略過的元素或字元數。 如果此值為 0 或更小的值，則會傳回值內的所有元素或字元。 如果此值大於陣列或字串的長度，則會傳回空白的陣列或字串。

傳回值

陣列或字串。

範例

下列範例會略過陣列中指定的元素數目，以及字串中指定的字元數。

param testArray array = [
  'one'
  'two'
  'three'
]
param elementsToSkip int = 2
param testString string = 'one two three'
param charactersToSkip int = 4

output arrayOutput array = skip(testArray, elementsToSkip)
output stringOutput string = skip(testString, charactersToSkip)

上述範例中具有預設值的輸出如下：

名稱 類型 值
arrayOutput 陣列 ["three"]
stringOutput String two three

split

split(inputString, delimiter)

傳回包含輸入字串之子字串的字串陣列，其中的子字串已使用指定的分隔符號分隔。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
inputString Yes string 要分隔的字串。
分隔符號 Yes 字串或字串陣列 用於分割字串的分隔符號。

傳回值

字串的陣列。

範例

下列範例會分割輸入字串，所使用的分割字元為逗號或分號。

param firstString string = 'one,two,three'
param secondString string = 'one;two,three'

var delimiters = [
  ','
  ';'
]

output firstOutput array = split(firstString, ',')
output secondOutput array = split(secondString, delimiters)

上述範例中具有預設值的輸出如下：

名稱 類型 值
firstOutput 陣列 ["one", "two", "three"]
secondOutput 陣列 ["one", "two", "three"]

startsWith

startsWith(stringToSearch, stringToFind)

判斷字串開頭是否為值。 此比較不區分大小寫。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
stringToSearch Yes string 其中包含要尋找之項目的值。
stringToFind Yes string 要尋找的值。

傳回值

如果第一個字元或字串字元與該值相符，則傳回 True；否則傳回 False。

範例

下列範例顯示如何使用 startsWith 和 endsWith 函式：

output startsTrue bool = startsWith('abcdef', 'ab')
output startsCapTrue bool = startsWith('abcdef', 'A')
output startsFalse bool = startsWith('abcdef', 'e')
output endsTrue bool = endsWith('abcdef', 'ef')
output endsCapTrue bool = endsWith('abcdef', 'F')
output endsFalse bool = endsWith('abcdef', 'e')

上述範例中具有預設值的輸出如下：

名稱 類型 值
startsTrue Bool True
startsCapTrue Bool True
startsFalse Bool False
endsTrue Bool True
endsCapTrue Bool True
endsFalse Bool False

string

string(valueToConvert)

將指定的值轉換成字串。 字串會依原樣傳回。 其他類型會轉換為其等效的 JSON 標記法。 如果您需要將字串轉換成 JSON，也就是引號/逸出，可以使用 substring(string([value]), 1, length(string([value]) - 2)。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
valueToConvert Yes 任意 要轉換成字串的值。 任何類型的值均可轉換，包括物件和陣列。

傳回值

轉換值的字串。

範例

下列範例顯示如何將不同類型的值轉換為字串︰

param testObject object = {
  valueA: 10
  valueB: 'Example Text'
}
param testArray array = [
  '\'a\''
  '"b"'
  '\\c\\'
]
param testInt int = 5
param testString string = 'foo " \' \\'

output objectOutput string = string(testObject)
output arrayOutput string = string(testArray)
output intOutput string = string(testInt)
output stringOutput string = string(testString)
output stringEscapedOutput string = substring(string([testString]), 1, length(string([testString])) - 2)

上述範例中具有預設值的輸出如下：

名稱 類型 值
objectOutput String {"valueA":10,"valueB":"Example Text"}
arrayOutput String ["'a'","\"b\"","\\c\\"]
intOutput String 5
stringOutput String foo " ' \
stringEscapedOutput String "foo \" ' \\"

substring

substring(stringToParse, startIndex, length)

傳回起始於指定字元位置的子字串，其中包含指定的字元數。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
stringToParse Yes string 要用來擷取子字串的原始字串。
startIndex No int 起始字元位置為零的子字串。
length No int 子字串的字元數。 必須參考字串內的位置。 必須是零或更大的值。 如果省略此值，則會傳回起始位置字串的其餘部分。

傳回值

子字串。 或著，如果長度為零，則為空字串。

備註

當子字串延伸超過字串的結尾，或當長度小於零時，此函式會失敗。 下列範例會失敗，並出現錯誤「索引與長度參數必須參考字串內的位置。 索引參數: '0'，長度參數: '11'，字串參數的長度: '10'。」。

param inputString string = '1234567890'

var prefix = substring(inputString, 0, 11)

範例

下列範例會從參數中擷取子字串。

param testString string = 'one two three'
output substringOutput string = substring(testString, 4, 3)

上述範例中具有預設值的輸出如下：

名稱 類型 值
substringOutput String 2

take

take(originalValue, numberToTake)

傳回由字串開頭的指定字元數目所形成的字串，或傳回由陣列開頭的指定元素數目所組成的陣列。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
originalValue Yes 陣列或字串 要從其中擷取元素的陣列或字串。
numberToTake Yes int 要擷取的元素或字元數。 如果此值為 0 或更小的值，則會傳回空白陣列或字串。 如果此值大於指定陣列或字串的長度，則會傳回陣列或字串中的所有元素。

傳回值

陣列或字串。

範例

下列範例會從陣列中取得指定的元素數目，以及從字串中取得指定的字元數目。

param testArray array = [
  'one'
  'two'
  'three'
]
param elementsToTake int = 2
param testString string = 'one two three'
param charactersToTake int = 2

output arrayOutput array = take(testArray, elementsToTake)
output stringOutput string = take(testString, charactersToTake)

上述範例中具有預設值的輸出如下：

名稱 類型 值
arrayOutput 陣列 ["one", "two"]
stringOutput String on

toLower

toLower(stringToChange)

將指定的字串轉換為小寫。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
stringToChange Yes string 要轉換成小寫字母的值。

傳回值

字串已轉換成小寫。

範例

下列範例會將參數值轉換為小寫和大寫。

param testString string = 'One Two Three'

output toLowerOutput string = toLower(testString)
output toUpperOutput string = toUpper(testString)

上述範例中具有預設值的輸出如下：

名稱 類型 值
toLowerOutput String one two three
toUpperOutput String ONE TWO THREE

toUpper

toUpper(stringToChange)

將指定的字串轉換為大寫。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
stringToChange Yes string 要轉換成大寫字母的值。

傳回值

字串已轉換成大寫。

範例

下列範例會將參數值轉換為小寫和大寫。

param testString string = 'One Two Three'

output toLowerOutput string = toLower(testString)
output toUpperOutput string = toUpper(testString)

上述範例中具有預設值的輸出如下：

名稱 類型 值
toLowerOutput String one two three
toUpperOutput String ONE TWO THREE

修剪

trim(stringToTrim)

從指定的字串中移除所有開頭和尾端空白字元。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
stringToTrim Yes string 要修剪的值。

傳回值

沒有開頭和尾端空白字元的字串。

範例

下列範例會修剪參數的空白字元。

param testString string = '    one two three   '

output return string = trim(testString)

上述範例中具有預設值的輸出如下：

名稱 類型 值
return String one two three

uniqueString

uniqueString(baseString, ...)

根據當作參數提供的值，建立具決定性的雜湊字串。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
baseString Yes string 雜湊函式中用來建立唯一字串的值。
視需要，也會使用其他參數 No string 您可以視需要新增多個字串，來建立指定唯一性層級的值。

備註

當您需要建立資源的唯一名稱時，這個函式很有幫助。 您提供限制結果唯一性範圍的參數值。 您可以指定名稱對於訂用帳戶、資源群組或部署是否唯一。

傳回的值不是隨機字串，而是雜湊函式的結果。 傳回的值為 13 個字元長。 這不是全域唯一的值。 建議您將值與來自命名慣例的前置詞結合，建立有意義的名稱。 下列範例顯示傳回值的格式。 依提供的參數而改變的實際值。

tcvhiyu5h2o5o

下列範例顯示如何使用 uniqueString 來建立常用層級的唯一值。

在訂用帳戶範圍內是唯一

uniqueString(subscription().subscriptionId)

在資源群組範圍內是唯一

uniqueString(resourceGroup().id)

在資源群組的部署範圍內是唯一

uniqueString(resourceGroup().id, deployment().name)

下列範例顯示如何根據您的資源群組建立儲存體帳戶的唯一名稱。 在資源群組內，如果名稱是以相同方式建構，就不會是唯一的名稱。

resource mystorage 'Microsoft.Storage/storageAccounts@2018-07-01' = {
  name: 'storage${uniqueString(resourceGroup().id)}'
  ...
}

如果您每次部署 Bicep 檔案時都需要建立新的唯一名稱，而且不想要更新資源，則可以使用 utcNow 函式搭配 uniqueString。 您可以在測試環境中使用此方法。 如需範例，請參閱 utcNow。 請注意，utcNow 函式只能在運算式中使用，以取得參數的預設值。

傳回值

包含 13 個字元的字串。

範例

下列範例會從 uniquestring 傳回結果：

output uniqueRG string = uniqueString(resourceGroup().id)
output uniqueDeploy string = uniqueString(resourceGroup().id, deployment().name)

uri

uri(baseUri, relativeUri)

藉由結合 baseUri 和 relativeUri 字串建立絕對 URI。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
baseUri Yes string 基底 uri 的字串。 請仔細觀察處理尾端斜線 ('/') 的相關行為，如下表所述。
relativeUri Yes string 要加入至基底 uri 字串的相對 uri 字串。

  • 如果 baseUri 以尾端斜線結尾，則結果只是 baseUri 後面接著 relativeUri。

  • 如果 baseUri 不是以尾端斜線結果，則會發生兩種結果。

    • 如果 baseUri 沒有任何斜線 (除了靠近前面的 "//" 之外)，則結果只是 baseUri 後面接著 relativeUri。

    • 如果 baseUri 有一些斜線，但不是以斜線結尾，則會在 baseUri 中移除從最後一個斜線開始的所有字串，結果會是 baseUri 後面接著 relativeUri。

以下列出一些範例：

uri('http://contoso.org/firstpath', 'myscript.sh') -> http://contoso.org/myscript.sh
uri('http://contoso.org/firstpath/', 'myscript.sh') -> http://contoso.org/firstpath/myscript.sh
uri('http://contoso.org/firstpath/azuredeploy.json', 'myscript.sh') -> http://contoso.org/firstpath/myscript.sh
uri('http://contoso.org/firstpath/azuredeploy.json/', 'myscript.sh') -> http://contoso.org/firstpath/azuredeploy.json/myscript.sh

如需完整的詳細資訊，請依照 RFC 3986 第 5 節中的規定，解析 baseUri 和 relativeUri 參數。

傳回值

字串，代表基底和相對值的絕對 URI。

範例

下列範例顯示如何使用 uri、uriComponent 和 uriComponentToString：

var uriFormat = uri('http://contoso.com/resources/', 'nested/azuredeploy.json')
var uriEncoded = uriComponent(uriFormat)

output uriOutput string = uriFormat
output componentOutput string = uriEncoded
output toStringOutput string = uriComponentToString(uriEncoded)

上述範例中具有預設值的輸出如下：

名稱 類型 值
uriOutput String http://contoso.com/resources/nested/azuredeploy.json
componentOutput String http%3A%2F%2Fcontoso.com%2Fresources%2Fnested%2Fazuredeploy.json
toStringOutput String http://contoso.com/resources/nested/azuredeploy.json

uriComponent

uricomponent(stringToEncode)

將 URI 編碼。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
stringToEncode Yes string 要編碼的值。

傳回值

URI 編碼值的字串。

範例

下列範例顯示如何使用 uri、uriComponent 和 uriComponentToString：

var uriFormat = uri('http://contoso.com/resources/', 'nested/azuredeploy.json')
var uriEncoded = uriComponent(uriFormat)

output uriOutput string = uriFormat
output componentOutput string = uriEncoded
output toStringOutput string = uriComponentToString(uriEncoded)

上述範例中具有預設值的輸出如下：

名稱 類型 值
uriOutput String http://contoso.com/resources/nested/azuredeploy.json
componentOutput String http%3A%2F%2Fcontoso.com%2Fresources%2Fnested%2Fazuredeploy.json
toStringOutput String http://contoso.com/resources/nested/azuredeploy.json

uriComponentToString

uriComponentToString(uriEncodedString)

傳回 URI 編碼值的字串。

命名空間：sys (部分機器翻譯)。

參數

參數 必要 類型​ 描述
uriEncodedString Yes string 要轉換為字串的 URI 編碼值。

傳回值

URI 編碼值的解碼字串。

範例

下列範例顯示如何使用 uri、uriComponent 和 uriComponentToString：

var uriFormat = uri('http://contoso.com/resources/', 'nested/azuredeploy.json')
var uriEncoded = uriComponent(uriFormat)

output uriOutput string = uriFormat
output componentOutput string = uriEncoded
output toStringOutput string = uriComponentToString(uriEncoded)

上述範例中具有預設值的輸出如下：

名稱 類型 值
uriOutput String http://contoso.com/resources/nested/azuredeploy.json
componentOutput String http%3A%2F%2Fcontoso.com%2Fresources%2Fnested%2Fazuredeploy.json
toStringOutput String http://contoso.com/resources/nested/azuredeploy.json

下一步