函数

Version 24.3.9111

函数

将函数视为一种特殊类型的格式化器，它会生成输出值，但不需要像标准格式化器那样输入。函数可以单独使用，也可以作为更复杂表达式的开始，其他格式化器在其后通过管道输入。例如，“[vault(foo)]”可以自行解析，但也可以将其用作表达式的开头（例如，“[vault(foo) equals(bar)]”来检查“ fooVault 值等于bar`）。

CSV 函数

csv(value)

从 CSV 文件加载数据后，可以使用 csv csvListRecords 运算器用于解析 CSV 文件，csv 格式化器是 CSV 数据的格式化器，其功能与其它格式化器一样，从 CSV 文档中生成值。

value：CSV 列标题的字符串，用于查找该列的值。请注意，如果 CSV 文件没有标题，如果 “requireheader” 属性被设置为 false，则可以通过通用索引（c1, c2, c3, …）访问列。

csv 示例

在以下片段中，ArcScript 在内存中定义了一个 CSV 文档。

<arc:set attr="data" value=
"column1,column2,column3
entry1,entry2,entry3
entry4,entry5,entry6"
/>

在下面的例子中，调用 “csvListRecords” 运算器，从示例 CSV 文档中显示 CSV 格式。

<arc:call op="csvListRecords">
Row [_index] values: [csv('column1')], [csv('column2')], [csv('column3')]
</arc:call>

这段代码将显示以下输出：

Row 1 values: entry1, entry2, entry3
Row 2 values: entry4, entry5, entry6

JSON 函数

hasjsonpath(jsonpath)

检查输入的 jsonpath 是否存在于 JSON 文档中并返回布尔值 (true/false)。

jsonpath: 要检查的相对 jsonpath。

示例

<arc:set attr="json.text">
  {
    "key1": null,
    "key2": "this is a string",
    "key3": "hello world",
    "key4": 123,
    "key5": {},
    "key6": \[],
    "key7": true
  }
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
  <!-- 这会检查所需的 jsonpath 是否存在，如果不存在则抛出错误。 -->
  <arc:if exp="[hasjsonpath(key10) | equals(false)]">
    <arc:throw code="noJSONPath" desc="The jsonpath you were looking for does not exist!" />
  </arc:if>
</arc:call>

isjsonpathnull(jsonpath, [ifTrue], [ifFalse])

检查输入的 jsonpath，如果 jsonpath 为 null 或不存在，则返回布尔值 (true/false)。

jsonpath：要检查的可选相对 json。
ifTrue：如果格式化器解析为 true，则返回可选值。
ifFalse：如果格式化器解析为 false，则返回可选值。

示例

<arc:set attr="json.text">
  {
    "key1": null,
    "key2": "this is a string",
    "key3": "hello world",
    "key4": 123,
    "key5": {},
    "key6": \[],
    "key7": true
  }
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
  <arc:if exp="[IsJSONPathNull(key1) | equals(true)]" >
    <!-- 这会执行，因为 key1 的值为 null -->
    <arc:set attr="_log.info" value="The jsonpath for key1 either has a value of null or does not exist." />
    <!-- 将格式化器的默认 true/false 输出覆盖为 1/0 -->
    <arc:if exp="[IsJSONPathNull(key10, 1, 0) | equals(1)]" >
      <!-- 之所以执行，是因为输入的 json 文本中不存在 key10 -->
      <arc:set attr="_log.info" value="The jsonpath for key10 either has a value of null or does not exist." />
    </arc:if>
  </arc:if>
</arc:call>

jsonpath(jsonpath)

jsonpath: The optional relative jsonpath to find the associated JSON value from. 可以在对具有可用 JSON DOM 的 JSON 操作的调用中使用此格式化器。可以使用 jsonDOMSearch 和 jsonDOMGet 操作来解析 JSON 文档。 jsonpath 格式化器是 DOM 对象的格式化器，其功能与其他格式化器类似，通过从 JSON 文档生成值来实现。 jsonpath 格式化器返回 JSON 文档的当前 jsonpath 位置。或者，可以提供相对 jsonpath 的字符串来查找关联的 JSON 值。
jsonpath：可选的相对 jsonpath，用于查找关联的 JSON 值。

示例

<arc:set attr="json.text">
  {
    "key1": null,
    "key2": "this is a string",
    "key3": "hello world",
    "key4": 123,
    "key5": {},
    "key6": \[],
    "key7": true
  }
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
  <!-- 这会打印“I just want to say, hello world!” 到应用程序日志-->
  <arc:set attr="_log.info" value="I just want to say, [jsonpath(key3)]!"/>
</arc:call>

jsonsubtree(jsonpath)

可以使用 jsonsubtree 从嵌套的 JSON 结构中解析 JSON 子树。

jsonpath：可选字符串，一个相对的 jsonpath，指示从结构的哪个级别开始。

示例

以下脚本包含 JSON 数据中 /json/Event/Attendees 对象下的三个 User 条目。Attendees 对象是根对象的子树。

<arc:setc attr="json.text">
{
  "Event": {
    "Subject": "Meeting",
    "Attendees": {
      "User": [
        {
          "Code": "1",
          "Name": "Jane Doe"
        },
        {
          "Code": "2",
          "Name": "John Smith"
        },
        {
          "Code": "3",
          "Name": "Alex Johnson"
        }
      ]
    }
  }
}
</arc:setc>
<arc:set attr="json.jsonpath" value="/json/Event/Attendees" />
<arc:call op="jsonDOMSearch" in="json">
<arc:set attr="_log.info">  <!-- 将结果记录到应用程序日志 -->
[jsonsubtree(.)]  <!-- 在括号内插入你想要的 jsonpath -->
</arc:set>
</arc:call>

在此示例中，jsonpath 是 . 字符，它指示脚本根据其在根对象中的位置使用当前 jsonpath。此处，该路径是 /json/Event/Attendees，它返回所有三个条目。

下图显示了它在Activity页面的应用程序选项卡中的显示方式：

以下是原始 JSON 子树结果：

"Attendees": {
      "User": [
        {
          "Code": "1",
          "Name": "Jane Doe"
        },
        {
          "Code": "2",
          "Name": "John Smith"
        },
        {
          "Code": "3",
          "Name": "Alex Johnson"
        }
      ]
    }

要仅显示 /json/Event/Attendees 中第二次出现的 User jsonpath 的子树，请将 jsonsubtree 格式化器调用中的路径替换为 jsonsubtree(User/\[2\])。这将产生以下输出：

{
  "Code": "2",
  "Name": "John Smith"
}

jsontype(jsonpath)

返回当前 JSON 名称/值对的数据类型（字符串、数字、对象、数组或布尔值）。

jsonpath：可选的相对 jsonpath，用于查找关联的 JSON 值。

示例

<arc:set attr="json.text">
  {
    "key1": null,
    "key2": "this is a string",
    "key3": "hello world",
    "key4": 123,
    "key5": {},
    "key6": \[],
    "key7": true
  }
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
  <!-- 创建一些描述输入 json 的各种元素的输出数据 -->
  <arc:set attr="output.data">The jsontype of key4 is [jsontype(key4)]
The jsontype of key5 is [jsontype(key5)]
The jsontype of key6 is [jsontype(key6)]
The jsontype of key7 is [jsontype(key7)]
  </arc:set>
</arc:call>

<arc:set attr="output.filename" value="output.txt" />
<arc:push item="output" /> 

<!--output.txt 的内容-->

The jsontype of key4 is NUMBER
The jsontype of key5 is OBJECT
The jsontype of key6 is ARRAY
The jsontype of key7 is BOOL

XML 函数

hasxpath(xpath)

检查输入的 xpath 是否存在于 XML 文档中并返回布尔值 (true/false)。

xpath: 要检查的相对xpath。

示例

<arc:set attr="xml.text">
  <Items>
    <Foo>Bar</Foo>
    <Bar>Foo</Bar>
  </Items>
</arc:set>
<arc:set attr="xml.xpath" value="/Items"/>
<arc:call op="xmlDOMSearch" in="xml" out="result">
  <!-- 这会检查所需的 xpath 是否存在，如果不存在则抛出错误 -->
  <arc:if exp="[hasxpath(helloworld) | equals(false)]">
    <arc:throw code="noXPath" desc="The xpath you were looking for does not exist!" />
  </arc:if>
</arc:call>

isxpathnull(xpath, [ifTrue], [ifFalse])

检查输入的 xpath，如果 xpath 为 null 或不存在，则以 xsi:nil XML 属性 (xsi:nil="true/false") 的形式返回一个布尔值。使用 ifTrue 和 ifFalse 参数指定条件满足和不满足时的备用值。

xpath：要检查的可选相对 xpath。
ifTrue：如果格式化器解析为 true，则返回可选值。
ifFalse：如果格式化器解析为 false，则返回可选值。

示例

<arc:set attr="xml.text">
  <Items>
    <Foo>Bar</Foo>
    <Bar>Foo</Bar>
    <helloworld xsi:nil="true" />
  </Items>
</arc:set>
<arc:set attr="xml.xpath" value="/Items"/>
<arc:call op="xmlDOMSearch" in="xml" out="result">
  <arc:if exp="[IsXPathNull(helloworld) | contains(true)]" >
    <!-- 之所以执行，是因为 'helloworld' 的 xsi:nil 属性设置为 true -->
    <arc:set attr="_log.info" value="The xpath for 'helloworld' either has a value of null or does not exist." />
    <!-- 覆盖格式化器的默认输出以使用 true/false。 如果exp为真，里面的脚本就会运行。 -->
    <arc:if exp="[IsXPathNull(waldo, true, false)]" >
      <!-- 执行此操作是因为输入 xml 文本中不存在 'waldo' 元素 -->
      <arc:set attr="_log.info" value="The xpath for 'waldo' either has a value of null or does not exist." />
    </arc:if>
  </arc:if>
</arc:call>

xpath(value)

xpath 格式化器可以在调用有 XML DOM 可用的 XML 运算器时使用。xmlDOMSearch 和 xmlDOMGet 运算器用于解析 XML 文档，而 xpath 格式化器是 DOM 对象的格式化器，其功能与其它格式化器一样，是从 XML 文档中生成值。xpath 格式化器返回 XML 文档的当前 XPath 位置。

value：可选值，相对 XPath 字符串，用于查找相关的 XML 值。

示例

在以下代码片段中，XML 文档是在 ArcScript 的内存中定义的。

<arc:set attr="text">
  <root>
    <A>遥遥领先</A>
    <A>
      <B>
        <C>继续领先</C>
      </B>
    </A>
    <A>
      <B>永远领先</B>
    </A>
  </root>
</arc:set>

在以下代码片段中，调用 xmlDOMSearch 操作并从示例 XML 文档中显示 XPath 格式化器。

<arc:call op="xmlDOMSearch?xpath=/root/A">
  当前 XPath 是 [xpath]，'B' 元素值为 [xpath(B) | empty("未指定")]
</arc:call>

当针对前面的 XML 文档运行时，此代码将显示以下输出。

当前 XPath 是 /root/A[1]，'B' 元素值为 未指定
当前 XPath 是 /root/A[2]，'B' 元素值为 未指定
当前 XPath 是 /root/A[3]，'B' 元素值为 永远领先

在前面的示例中，XPath 格式化器迭代显示的三个 A 元素。但仅显示最终 B 元素中的 “永远领先”，因为 [xpath(B)] 会忽略其他元素中的值。

xpathcount(value)

xpathcount 格式化器与 xpath 格式化器非常相似，不同之处在于它返回与所提供的 XPath 匹配的元素的计数。它可以在对具有可用 XML DOM 的 XML 操作的调用中使用。可以使用 xmlDOMSearch 和 xmlDOMGet 运算器来解析 XML 文档，而 xpathcount 格式化器是 DOM 对象的格式化器，其功能与其他格式化器类似，通过从 XML 文档生成计数来实现。

value: 可选值，相对 XPath 字符串，用于查找相关的 XML 元素。

示例

<arc:set attr="xml.xpath" value="/Items/Cars/Subaru" />
<arc:set attr="xml.text">
 <Items>
  <Cars>
    <Subaru>
      <Color>Blue</Color>
      <Year>2017</Year>
    </Subaru>
    <Honda>
      <Color>Red</Color>
    </Honda>
  </Cars>
</Items>
</arc:set>
<arc:call op="xmlDOMSearch" in="xml" out="result">
  <!-- xpathcount 是 ArcScript 中的上下文相关函数。 如果 XML 文档加载到
        search，xpathcount 返回与提供的 xpath 匹配的元素数量的计数。 -->
  <arc:set attr="output.Data" value="[xpathcount('/Items/Cars/*/Color')]" />
</arc:call>

<arc:set attr="output.filename" value="test.txt" />
<arc:push item="output" />

运行此代码时，它会返回“2”作为输出。

xsubtree(value)

可以使用 xsubtree 从嵌套的 XML 结构中解析 XML 树。

xpath：可选字符串，相对 XPath 指示从结构的哪个级别开始。

示例

在下面的示例 XML 文档中，/Event/Attendees 下有三个条目。

<arc:set attr="xml.text">
<Event>
    <Subject>Meeting</Subject>
    <Attendees>
        <User>
            <Code>1</Code>
            <Name>TEST1</Name>
        </User>
        <User>
            <Code>2</Code>
            <Name>TEST2</Name>
        </User>
        <User>
            <Code>3</Code>
            <Name>TEST3</Name>
        </User>
    </Attendees>
</Event>
</arc:set>

<arc:set attr="xml.xpath" value="/Event/Attendees" />
<arc:call op="xmlDOMSearch" in="xml">
  [xsubtree(.)]  <!-- 在括号中插入所需的 XPath -->
</arc:call>

xsubtree 命令中的 . 字符指示脚本使用当前的 xpath。在本例中，路径是 /Event/Attendees ，它返回所有三个条目:

<User>
  <Code>1</Code>
  <Name>TEST1</Name>
</User>
<User>
  <Code>2</Code>
  <Name>TEST2</Name>
</User>
<User>
  <Code>3</Code>
  <Name>TEST3</Name>
</User>

如果你只想显示在 /Event/Attendees xpath 中第二次出现的 User 子树，你可以用 xsubtree(User\[2\]) 替换该命令。这样做的结果将是:

<User>
  <Code>2</Code>
  <Name>TEST2</Name>
</User>

其他函数

guid(includehyphens)

生成全局唯一标识符 (GUID) 值。默认情况下，格式化器返回单个未格式化字符串中的所有字符。要包含符合标准 8-4-4-4-12 GUID 格式的连字符，请使用 includehyphens 参数，并将其设置为 true。

此格式化器不会修改输入属性（变量），因此不需要这样的输入属性。

示例

<arc:set attr="myGUID" value="[guid(true)]" />

vault(ItemName, [ifnotexists])

返回全局配置库中与为 ItemName 提供的值匹配的项目的值。

ItemName：要检索的配置库项目的名称。
ifnotexists：为防止在配置库项目不存在时抛出错误，请提供此可选参数和默认值，例如 值不存在。当不存在具有指定 ItemName 的配置库项目时，将返回该值。

注意：在脚本上下文中引用加密配置库项目时请务必小心，以确保日志中不包含敏感信息。

示例

<:set attr="URLtoResource" value="[Vault(commonURL)]" />