ReadPropertySet 政策

概览

ReadPropertySet 政策会读取属性集，并使用结果填充流变量。

此政策为标准政策，可部署到任何环境类型。并非所有用户都需要了解政策和环境类型。如需了解政策类型以及在每种环境类型中的可用性，请参阅政策类型。

<ReadPropertySet> 元素

定义 ReadPropertySet 政策。

默认值 请参阅下面的默认政策标签页
是否必需？ 必需
类型 复杂对象
父元素 不适用
子元素 <Read>

<ReadPropertySet> 元素使用以下语法：

语法

<ReadPropertySet> 元素使用以下语法：

<ReadPropertySet name="read-property-set">
  <Read>
    <Name ref="set-ref">property-set-name</Name>
    <Key ref="key-ref">key-name</Key>
    <AssignTo>var1</AssignTo>
    <DefaultValue>default-value</DefaultValue>
  </Read>
  ...
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ReadPropertySet>

默认政策

以下示例展示了在 Apigee 界面中将 ReadPropertySet 政策添加到流时的默认设置：

<ReadPropertySet name="read-property-set">
  <Read>
    <Name ref="set-ref">property-set-name</Name>
    <Key ref="key-ref">key-name</Key>
    <AssignTo>var1</AssignTo>
    <DefaultValue>default-value</DefaultValue>
  </Read>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ReadPropertySet>

当您在 Apigee 界面中插入新的 ReadPropertySet 政策时，模板包含所有可能操作的存根。如需了解所需的元素，请参阅下文。

此元素具有所有政策中常见的以下属性：

属性 默认 是否必需？ 说明
name 无 必需

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
continueOnError 否 可选 设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅：
enabled true 可选 设置为 true 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
async   否 已弃用 此属性已弃用。

下表简要介绍了 <ReadPropertySet> 的子元素：

子元素 是否必需？ 说明
<Read> 需要 读取并解析属性集变量，并将其设置为指定的流变量。
<IgnoreUnresolvedVariables> 可选 确定在属性集无法解析时是否停止处理。

示例

本部分提供了使用 <ReadPropertySet> 的示例。

示例

此示例使用 <ReadPropertySet> 获取 propertyset.environment.name.request.headers.api-version 并将其分配给 target_url。如果未获取属性集值，则系统会改用 https://httpbin.org/get。

<ReadPropertySet name="read-property-set">
  <Read>
    <Name ref="set-ref">environment.name</Name>
    <Key ref="key-ref">request.headers.api-version</Key>
    <AssignTo>target_url</AssignTo>
    <DefaultValue>https://httpbin.org/get</DefaultValue>
  </Read>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</ReadPropertySet>

子元素参考

本部分介绍 <ReadPropertySet> 的子元素。

<Read>

解析属性集变量并在流变量中设置结果。

<Read> 元素指定要解析的属性集变量以及将该值设置为哪个流变量。该元素还包含一个可选的默认值，在属性集无法解析时系统会使用该值。您可以在单个 <ReadPropertySet> 政策中添加多个 <Read> 元素。

默认值 不适用
是否必需？ 可选
类型 复杂类型
父元素 <ReadPropertySet>
子元素 <Name>
<Key>
<AssignTo>
<DefaultValue>

<Read> 元素使用以下语法：

语法

<Read>
  <Name ref="set-ref">property-set-name</Name>
  <Key ref="key-ref">key-name</Key>
  <AssignTo>var1</AssignTo>
  <DefaultValue>default-value</DefaultValue>
</Read>

示例

此示例使用 <ReadPropertySet> 获取 propertyset.environment.name.request.headers.api-version 并将其分配给 target_url。如果未获取属性集值，则系统会改用 https://httpbin.org/get。

<ReadPropertySet name="read-property-set">
  <Read>
    <Name ref="environment.name">my-property-set-name</Name>
    <Key ref="request.headers.api-version">my-property-set-key</Key>
    <AssignTo>target_url</AssignTo>
    <DefaultValue>https://httpbin.org/get</DefaultValue>
  </Read>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</ReadPropertySet>

下表简要介绍了 <Read> 的子元素。

子元素 是否必需？ 说明
<Name> 需要 字符串

要从中读取数据的属性集。提供 ref 和/或值。

Apigee 会先尝试根据 ref 再根据值来解析 Name。如果两者都无法解析，则系统会应用 <DefaultValue>（如果提供）。

<Name> 和 <Key> 组合在一起为 propertyset.{value_resolved_from_Name}.{value_resolved_from_Key}。

<Key> 需要 字符串

解析变量时使用的属性集的键。 提供 ref 和/或值。

Apigee 会先尝试根据 ref 再根据值来解析 Key。如果两者都无法解析，则系统会应用 <DefaultValue>（如果提供）。

<Name> 和 <Key> 组合在一起为 propertyset.{value_resolved_from_Name}.{value_resolved_from_Key}。

<AssignTo> 需要 字符串

指定要将已解析的变量分配给哪个流变量。
<DefaultValue> 可选 字符串

指定无法解析变量时要使用的默认值。

<IgnoreUnresolvedVariables>

确定在属性集无法解析时是否停止处理。设置为 true 可忽略无法解析的变量并继续处理。

如果提供了 <DefaultValue>，则 IgnoreUnresolvedVariables 不适用。

默认值 否
是否必需？ 可选
类型 布尔值
父元素 <ReadPropertySet>
子元素 无

错误参考信息

本部分介绍了 Apigee 针对 <ReadPropertySet> 政策返回的故障代码和错误消息以及设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因
steps.readpropertyset.UnresolvedVariable 500

如果 ReadPropertySet 政策中指定的变量为以下任一情况，则会出现此错误：

  • 超出范围（在执行政策的特定流中不可用）
    • 或
  • 无法解析（未定义）。

如果 <IgnoreUnresolvedVariables> 为 false 且未指定 <DefaultValue>，则解析会失败。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称 原因
steps.readpropertyset.EmptyReads 该政策没有 <Read> 子元素。
steps.readpropertyset.FieldUnset 满足以下任一条件时，系统会返回此代码：
  • 没有为 <Name> 设置引用和名称
  • 没有为 <Key> 设置引用和名称
  • 没有为 <AssignTo> 提供值

故障变量

当此政策在运行时触发错误时，将设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量 其中 示例
fault.name="FAULT_NAME" FAULT_NAME 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 fault.name Matches "UnresolvedVariable"
readpropertyset.POLICY_NAME.failed POLICY_NAME 是抛出故障的政策的用户指定名称。 readpropertyset.RPS-SetResponse.failed = true

错误响应示例

  {
    "fault": {
      "faultstring": "ReadPropertySet[RPS-SetResponse]: unable to resolve variable [variable_name]",
      "detail": {
        "errorcode": "steps.readpropertyset.UnresolvedVariable"
      }
    }
  }

故障规则示例

  <FaultRule name="ReadPropertySet Faults">
      <Step>
          <Name>RPS-CustomSetVariableErrorResponse</Name>
          <Condition>(fault.name = "SetVariableFailed")</Condition>
      </Step>
      <Condition>(readpropertyset.failed = true)</Condition>
  </FaultRule>

架构

每种政策类型均由 XML 架构 (.xsd) 定义。GitHub 提供了政策架构作为参考。