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 政策时，模板包含所有可能操作的存根。如需了解所需的元素，请参阅下文。

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also:
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

下表简要介绍了 <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 满足以下任一条件时，系统会返回此代码：

故障变量

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

变量 其中 示例
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 提供了政策架构作为参考。