转载

REST 管理接口与 IBM DataPower Gateway: 第 2 部分：配置管理

简介

在 IBM DataPower Gateway 设备的固件版本 7.2.0.0 中，REST 管理接口提供了端到端的配置管理能力。您可检索和查看现有的配置，在现有配置上执行更新，创建配置，以及删除配置。在本系列的第 2 部分中，我们将了解检索、修改和删除现有配置的请求。还会学习如何构造请求载荷来创建配置。有关其他请求类型的信息，比如状态监视，文件和目录管理，以及设备操作，请参阅本系列中的其他部分。

回页首

检索现有配置

在本节中，检索设备上的对象的配置。

识别对象类

要开始检索设备中的现有配置，首先需要确定相关的对象类。要确定所需类的名称，可访问 REST 管理接口的根统一资源标识符 (URI)（如以下请求所示）来确定配置根 URI：

GET https://dphost.com:5554/mgmt/

在收到的响应中，如清单 1 所示，可以找到配置根 URI /mgmt/config/ 。

清单 1. 根 URI 响应

{    "_links": {      "self": {        "href": "/mgmt/"     },      "config": {        "href": "/mgmt/config/"     },      "domains": {        "href": "/mgmt/domains/config/"     },      "status": {        "href": "/mgmt/status/"     },      "actionqueue": {        "href": "/mgmt/actionqueue/"     },      "filestore": {        "href": "/mgmt/filestore/"     },      "metadata": {        "href": "/mgmt/metadata/"     },      "types": {        "href": "/mgmt/types/"     }    }   }

访问配置根 URI /mgmt/config/ 来检索设备上所有可用对象类的列表，如以下请求所示：

GET https://dphost.com:5554/mgmt/config/

要确定类名称的准确格式，可搜索收到的响应载荷，清单 2 中显示了其中的一部分。

清单 2. 配置根 URI 的部分响应

{    "_links": {      "self": {        "href": "/mgmt/config/"     }    },    "AAAPolicy": {      "href": "/mgmt/config/{domain}/AAAPolicy"   },    "AccessControlList": {      "href": "/mgmt/config/{domain}/AccessControlList"   },    "AppSecurityPolicy": {      "href": "/mgmt/config/{domain}/AppSecurityPolicy"   },    "AS2ProxySourceProtocolHandler": {      "href": "/mgmt/config/{domain}/AS2ProxySourceProtocolHandler"   },    "AuditLog": {      "href": "/mgmt/config/{domain}/AuditLog"   },    "CertMonitor": {      "href": "/mgmt/config/{domain}/CertMonitor"   },    "CloudConnectorService": {      "href": "/mgmt/config/{domain}/CloudConnectorService"   },    ...   }

作为确定对象类的格式的备用方法，可以在访问一个对象或对象列表时检查 WebGUI 浏览器窗口中显示的 URI。

检索对象类列表

确定类名称的格式后，可以检索目标类的现有对象列表。要检索该列表，需要构造一个 /mgmt/config/{domain}/{class_name} 格式的 URI，将 {domain} 替换为目标域，将 {class_name} 替换为目标类。下面的示例中显示了这个 URI，其中目标域为 my-testing-domain ，类名称为 HTTPSourceProtocolHandler ：

GET https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler

对类列表请求的响应会返回目标域内该类的所有对象。如果不存在该类的对象，将返回一条告知消息，如清单 3 所示。

清单 3. 对象类列表响应

{    "_links": {      "self": {        "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler"     }    },    "result": "no configuration retrieved"   }   }

检索对象级配置

如果一个域中存在一个特定类的至少一个对象，可以检索该对象的配置。要检索该配置，需要构造一个 /mgmt/config/{domain}/{class_name}/{object_name} 格式的 URI。在这个格式中，将 {domain} 替换为目标域，将 {class_name} 替换为对象类，将 {object_name} 替换为特定的对象实例。

下面这个请求显示了这个 URI。在这里，目标域为 my-testing-domain ，类名称为 HTTPSourceProtocolHandler ，对象名称为 test-HTTP-SPH 。

GET https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/   test-HTTP-SPH

对一个对象检索请求的响应返回目标域内一个特定对象实例的配置，如清单 4 所示。

清单 4. 对象检索响应

{    "_links": {      "self": {        "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/test-HTTP-SPH"     },      "doc": {        "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     }    },    "HTTPSourceProtocolHandler": {      "name": "test-HTTP-SPH",      "mAdminState": "enabled",      "LocalAddress": "0.0.0.0",      "LocalPort": 8001,      "HTTPVersion": "HTTP/1.1",      "AllowedFeatures": {        "HTTP-1.0": "on",        "HTTP-1.1": "on",        "POST": "on",        "GET": "off",        "PUT": "on",        "HEAD": "off",        "OPTIONS": "off",        "TRACE": "off",        "DELETE": "off",        "CONNECT": "off",        "CustomMethods": "off",        "QueryString": "on",        "FragmentIdentifiers": "on",        "DotDot": "off",        "CmdExe": "off"     },      "PersistentConnections": "on",      "MaxPersistentConnectionsReuse": 0,      "AllowCompression": "off",      "AllowWebSocketUpgrade": "off",      "WebSocketIdleTimeout": 0,      "MaxURLLen": 16384,      "MaxTotalHdrLen": 128000,      "MaxHdrCount": 0,      "MaxNameHdrLen": 0,      "MaxValueHdrLen": 0,      "MaxQueryStringLen": 0    }   }

检索属性级配置

也可以检索一个特定属性的值，而不检索完整的对象配置。要检索该值，可构造一个以下格式的 URI： /mgmt/config/{domain}/{class_name}/{object_name}/{property_name} 。在这个 URI 中，将 {domain} 替换为目标域，将 {class_name} 替换为对象类，将 {object_name} 替换为对象实例。另外，将 {property_name} 替换为清单 4中完整的对象配置响应中显示的特定属性名称。

下面这个请求显示了这个 URI。在这里，目标域为 my-testing-domain ，类名称为 HTTPSourceProtocolHandler ，对象名称为 test-HTTP-SPH ，属性名称为 LocalPort 。

GET https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/   test-HTTP-SPH/LocalPort

对一个对象属性检索请求的响应返回这个特定对象属性的值，如清单 5 所示。

清单 5. 对象属性检索响应

{    "_links": {      "self": {  "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/        test-HTTP-SPH/LocalPort"     },      "doc": {        "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     }    },    "LocalPort": 8003   }

回页首

修改和删除现有的配置

在本节中，修改和删除设备上对象的配置。

修改属性级配置

要修改一个现有的属性值，可以将现有值重写为一个包含更新的值的载荷。要重写该值，可检索当前的属性值。对于使用 HTTPSourceProtocolHandler 对象的示例，请参阅检索对象级配置和检索属性级配置中的请求和响应。

接下来，检查当前属性值以确定变化。确定当前变化后，修改收到的属性载荷（如清单 5所示）以删除 _links{} 节。任何引用设备上的其他配置对象的属性也必须删除嵌入的 href 链接。清单 6 显示了带载荷的结果，该载荷包含 LocalPort 的一个更新的属性值。

清单 6. 修改后的属性级载荷

{    "LocalPort": 8012   }

创建修改后的载荷后，发送一个 HTTP PUT 请求来重写现有的属性值，如下面这个示例中所示。在属性级别上更新配置，可以使用一个请求更新一个属性值。要使用一个请求更新多个属性值，需要对象级别上的更新。

PUT https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/   test-HTTP-SPH/LocalPort

更新目标属性后，会收到一条确认响应，如清单 7 所示。

清单 7. 对象属性修改响应

{    "_links": {      "self": {        "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/                 test-HTTP-SPH/LocalPort"     },      "doc": {        "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     }    },    "LocalPort": "property has been updated."  }

修改对象级配置

要修改现有的对象配置，可将现有的配置重写为一个更新的载荷。要重写配置，需要检索要修改的对象的当前配置。检索对象级配置中对 HTTPSourceProtocolHandler 对象的检索请求展示了此请求的一个例子。

然后检查当前配置（如清单 4中所示）来确定配置变化。识别当前变化后，修改清单 4中收到的载荷，以删除应保持不变的 _links{} 节和所有属性。删除任何引用了设备上其他配置对象的属性的嵌入式 href 链接，如清单 8 所示。在此清单中，载荷包含 mAdminState 、 LocalAddress 、 LocalPort 和 HTTPVersion 的更新属性值。

清单 8. 修改后的对象级载荷

{    "HTTPSourceProtocolHandler": {      "name": "test-HTTP-SPH",      "mAdminState": "disabled",      "LocalAddress": "1.2.3.4",      "LocalPort": 8005,      "HTTPVersion": "HTTP/1.0"   }   }

创建修改后的载荷后，发送一个 HTTP PUT 请求来重写现有配置：

PUT https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/   test-HTTP-SPH

在对象级别上更新配置，可以使用一个请求更新多个属性值。也可以在属性级别上更新单个属性值，如修改属性级配置中所述。

更新目标对象实例后，您会收到一条确认响应，如清单 9 所示。

清单 9. 对象修改响应

{    "_links": {      "self": {        "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/test-HTTP-SPH"     },      "doc": {        "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     },      "test-HTTP-SPH": "Configuration has been updated."  }

删除对象级配置

仅支持对象级别上的配置删除。对象 DELETE 请求不应收到请求载荷。如果提供了载荷，会触发下面这个请求来报告故障：

DELETE https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/   test-HTTP-SPH

处理删除请求后，您会收到一条确认响应，如清单 10 所示。

清单 10. 对象删除响应

{    "_links": {      "self": {        "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/test-HTTP-SPH      },      "doc": {        "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     }    },    "HTTPSourceProtocolHandler": {      "value": "Configuration has been deleted."   }   }

不支持删除单个对象属性。要删除一个可选的属性或将需要的属性重置为它的默认值，需要删除并重新创建整个配置对象。从请求载荷中省略特定属性的值。列表属性或包含多个同类型条目的属性会以不同方式得到处理。列表属性允许更新，不需要首先删除整个对象配置。有关更多信息，请参阅修改列表属性。

回页首

创建配置

在本节中，我们要在设备上创建配置对象。还要构造有效的请求载荷并发送请求来创建对象。

构造有效的请求载荷

要创建一种对象配置，可构造一个包含新配置的有效载荷。如果无法在 REST 管理接口的响应载荷中检查同一个对象类来构造有效的载荷，如检索对象级配置和清单 4中所示，可使用另一种方法。

要开始构造该载荷，需确定目标对象的结构描述，也就是对象模式。可以从两个来源检索此信息：REST 管理接口的元数据资源和设备的面向服务管理接口 (SOMA) 模式。可以选择使用何种方法来构造有效的载荷，因为您不需要同时参阅两种来源。

要从 REST 管理接口的元数据资源检索对象模式，可访问 REST 管理接口的元数据根 URI：

GET https://dphost.com:5554/mgmt/metadata/

从元数据根 URI 返回的响应（参见清单 11）显示了可用于在 object 链接内检索配置对象模式的选项： /mgmt/metadata/{domain}/{object_name} 。

清单 11. 元数据根 URI 响应

{    "_links": {      "self": {        "href": "/mgmt/metadata/"     },      "object": {        "href": "/mgmt/metadata/{domain}/{object_name}"     },      "property": {        "href": "/mgmt/metadata/{domain}/{object_name}/{property_name}"     },      "operation": {        "href": "/mgmt/metadata/{domain}/operations/{operation_name}"     }    }   }

要检索对象元数据，可输入下面这个请求。其中，对于 {domain} ，替换 my-testing-domain ，对于 {object_name} ，替换 HTTPSourceProtocolHandler 对象类。

GET https://dphost.com:5554/mgmt/metadata/my-testing-domain/HTTPSourceProtocolHandler

从元数据资源检索的信息是相同的，无论 {domain} 标识符是什么。需要 {domain} 标识符来确保用户拥有目标域的访问权限。

取决于目标对象类，从元数据请求返回的响应可能很大。构造一个请求载荷的相关信息包含在响应的 properties 元素中，如清单 12 中的 HTTPSourceProtocolHandler 类所示。此列表包括所有目标对象属性，以及最小和最大值、需要的属性和默认值等信息。

清单 12. 元数据检索响应

{    "_links": {      "self": {        "href": "/mgmt/metadata/my-testing-domain/HTTPSourceProtocolHandler"     },      "doc": {        "href": "/mgmt/docs/metadata/HTTPSourceProtocolHandler"     }    },    "object": {      "name": "HTTPSourceProtocolHandler",      "uri": "protocol/http",      "cli-alias": "source-http",      ...      "properties": {        "property": [          {            "name": "mAdminState",            "type": {              "href": "/mgmt/types/default/dmAdminState"           },            "cli-alias": "admin-state",            "default": "enabled",            ...          },          {            "name": "UserSummary",            "type": {              "href": "/mgmt/types/default/dmString"           },            "cli-alias": "summary",            ...          },          {            "name": "LocalAddress",            "type": {              "href": "/mgmt/types/default/dmLocalIPHostAddress"           },            "required": "true",            "cli-alias": "local-address",            "default": "0.0.0.0",            ...          },          {            "name": "LocalPort",            "type": {              "href": "/mgmt/types/default/dmIPPort"           },            "required": "true",            "cli-alias": "port",            "minimum": 1,            "maximum": "0xFFFF",            "default": 80,            ...          },          {            "name": "HTTPVersion",            "type": {              "href": "/mgmt/types/default/dmHTTPVersion"           },            "cli-alias": "http-client-version",            "default": "HTTP/1.1",            ...          },          ...        ]      }    }   }

要为从 REST 管理接口的元数据资源检索的信息提供补充，可以探究目标对象的 SOMA 模式。设备上的 store:///xml-mgmt.xsd 文件内的默认域中提供了所有配置对象的 SOMA 模式。搜索一个对象类会得到一种与清单 13 中的 HTTPSourceProtocolHandler 类的模式类似的模式。通过检查 minOccurs 和 maxOccurs 特性，很容易看到为 REST 管理接口构造请求载荷所需的相关信息。例如，可以看到需要哪些属性。

清单 13. 一个目标对象的 SOMA 模式

<xsd:complexType name="ConfigHTTPSourceProtocolHandler">    <xsd:complexContent>      <xsd:extension base="tns:ConfigSourceProtocolHandler">        <xsd:choice maxOccurs="unbounded">          <xsd:element name="UserSummary" minOccurs="0" maxOccurs="1">            <xsd:simpleType>              <xsd:union memberTypes="tns:dmString tns:dmEmptyElement" />            </xsd:simpleType>          </xsd:element>          <xsd:element name="LocalAddress" minOccurs="1" maxOccurs="1">            <xsd:simpleType>              <xsd:union memberTypes="tns:dmLocalIPHostAddress tns:dmEmptyElement" />            </xsd:simpleType>          </xsd:element>          <xsd:element name="LocalPort" minOccurs="1" maxOccurs="1">            <xsd:simpleType>              <xsd:union memberTypes="tns:dmIPPort tns:dmEmptyElement" />            </xsd:simpleType>          </xsd:element>          <xsd:element name="HTTPVersion" minOccurs="0" maxOccurs="1">            <xsd:simpleType>              <xsd:union memberTypes="tns:dmHTTPVersion tns:dmEmptyElement" />            </xsd:simpleType>          </xsd:element>           ...        </xsd:choice>        ...      </xsd:extension>    </xsd:complexContent>   </xsd:complexType>

通过依赖于 REST 管理接口的元数据资源和设备 SOMA 模式，可以确定创建目标对象所需的属性。也可以确定要在载荷中使用的属性名称。通过使用此信息，可以构造一个恰当的 JSON 请求载荷，如清单 14 所示。

清单 14. 请求载荷结构

{    "{object_class_name}": {      "name": "{object_name}",      "{property1_name}": "{property1_value}",      "{property2_name}": "{property2_value}",      "{property3_name}": "{property3_value}",      "{property4_name}": "{property4_value}"     ...    }   }

替换 {object_class_name} 、 {object_name} 和所有需要的属性及其值时，会为 REST 管理接口创建一个有效的 JSON 请求载荷。清单 15 显示了一个用于创建 HTTPSourceProtocolHandler 对象的有效载荷，其中设置了 mAdminState 、 LocalAddress 、 LocalPort 和 HTTPVersion 的属性值。

清单 15. 有效的请求载荷

{    "HTTPSourceProtocolHandler": {      "name": "test-HTTP-SPH",      "mAdminState": "enabled",      "LocalAddress": "0.0.0.0",      "LocalPort": 8001,      "HTTPVersion": "HTTP/1.1"   }   }

创建有效的请求 URI

要创建配置对象，有两种方法可供选择。两种方法实现相同的结果，但针对不同的 URI。第一种方法使用一个 HTTP POST 请求，第二种使用一个 HTTP PUT 请求。使用 POST 请求创建对象，因为如果目标域中存在一个具有相同名称的对象，POST 请求会导致故障。此方法可预防意外地重写现有的对象配置。但是，也可使用 PUT 请求创建对象配置。在现有的对象配置上发出一个 PUT 请求，会将该配置重写为请求载荷中的值。

要使用 POST 请求创建配置对象，可按如下方式构建一个 URI 并为 {domain_name} 和 {class_name} 使用合适的替换值：

POST https://dphost.com:5554/mgmt/config/{domain_name}/{class_name}

要使用 PUT 请求创建配置对象，可构造一个如以下请求中所示的 URI。为 {domain_name} 、 {class_name} 和 {object_name} 使用合适的替换值。URI 和请求载荷中的 {object_name} 必须匹配。否则会导致错误。

PUT https://dphost.com:5554/mgmt/config/{domain_name}/{class_name}/{object_name}

发送一个请求并解释响应

构造请求载荷和目标 URI 后，发送一个 POST 请求或 PUT 请求来创建一个对象配置。下面的例子展示了如何使用 POST 请求创建一个 HTTPSourceProtocolHandler 对象：

POST https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler

下面的例子展示了如何使用 PUT 请求创建同一个对象：

PUT https://dphost.com:5554/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler/   test-HTTP-SPH

对于两种请求类型， {domain_name} 、 {class_name} 和 {object_name} 值都替换为创建有效的请求 URI中所示的相同值。

POST 和 PUT 请求在成功创建对象后返回相同的响应，如清单 16 所示。

清单 16. 对象创建响应

{    "result": "",    "_links": {      "self": {        "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler"     },      "doc": {        "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"     }    },    "test-HTTP-SPH": "Configuration has been created."  }

接下来发送到同一个目标 URI 的 POST 和 PUT 请求会生成不同的响应。对现有配置对象的后续 POST 请求会导致错误，如清单 17 所示。

清单 17. 对下一个 POST 请求的响应

{    "_links": {      "self": {        "href": "/mgmt/config/my-testing-domain/HTTPSourceProtocolHandler"     }    },    "error": "Resource already exists."  }

对现有配置对象的后续 PUT 请求会导致使用传入的载荷中的信息重写该对象，如清单 18 所示。

清单 18. 对下一个 PUT 请求的响应

{    "_links": {      "self": {        "href": "/mgmt/config/my-testing-domain/        HTTPSourceProtocolHandler/test-HTTP-SPH"     },      "doc": {        "href": "/mgmt/docs/config/HTTPSourceProtocolHandler"   },    "test-HTTP-SPH": "Configuration has been updated."  }

回页首

修改列表属性

在配置管理上下文中，列表属性需要特别考虑。如果一个属性包含多个同类型的项，那么它就是列表。例如，一个部署策略对象可能包含 3 个列表属性：已接受的配置、过滤后的配置和修改后的配置。类似于其他属性，列表属性允许使用 HTTP GET 和 PUT 方法来执行配置检索和更新。下面这个请求用于对一个部署策略对象执行列表属性检索：

GET https://dphost.com:5554/mgmt/config/default/ConfigDeploymentPolicy/test/AcceptedConfig

如清单 19 中所示， AcceptedConfig 属性包含 4 个条目。

清单 19. 列表属性检索响应

{    "_links": {      "self": {      "href": "/mgmt/config/default/ConfigDeploymentPolicy/test/AcceptedConfig"     },      "doc": {        "href": "/mgmt/docs/config/ConfigDeploymentPolicy"     }    },    "AcceptedConfig": [      "*/*/config/deployment-policy-variables?Name=pdp-params_1",      "*/*/config/deployment?Name=pdp-dp_1",      "*/*/config/pattern?Name=.*",      "*/*/services/sslforwarder?Name=SSLProxyService_test"   ]   }

列表属性也支持 POST 和 DELETE HTTP 方法，但其他属性类型不支持。有关列表属性上的 POST 和 DELETE 方法的更多信息，请参阅以下各节。

附加到一个列表属性

使用 POST 请求将更多值附加到列表属性中，可在关联的载荷内提供更多配置条目。

首先，为一个部署策略对象的 AcceptedConfig 属性创建一个包含更多列表条目的请求载荷，如清单 20 所示。

清单 20. 一个列表属性的更多条目

{     "AcceptedConfig": [        "value": "*/*/config/deployment-policy-variables?Name=pdp-params_2",        "value": "*/*/config/deployment?Name=pdp-dp_2"     ]   }

然后，发送一个 POST 请求来将更多的列表条目（来自清单 20）附加到 AcceptedConfig 属性：

POST https://dphost.com:5554/mgmt/config/default/ConfigDeploymentPolicy/   test/AcceptedConfig

完成该请求后，会返回一条确认响应，如清单 21 所示。

清单 21. 附加列表属性的响应

{    "_links": {      "self": {        "href": "/mgmt/config/default/ConfigDeploymentPolicy/test/AcceptedConfig"     },      "doc": {        "href": "/mgmt/docs/config/ConfigDeploymentPolicy"     }    },    "AcceptedConfig": "property has been updated."  }

清除一个列表属性

可使用 DELETE 请求从列表属性中清除所有当前值。此请求不需要任何请求载荷。

DELETE https://dphost.com:5554/mgmt/config/default/ConfigDeploymentPolicy/   test/AcceptedConfig

完成该请求后，会返回一条确认响应，如清单 22 所示。

清单 22. 清除列表属性的响应

{    "_links": {      "self": {        "href": "/mgmt/config/default/       ConfigDeploymentPolicy/test/AcceptedConfig"     },      "doc": {        "href": "/mgmt/docs/config/ConfigDeploymentPolicy"     }    },    "AcceptedConfig": "property has been deleted."  }

回页首

修改位图属性

在配置管理上下文中，位图属性也需要特别考虑。如果一个属性包含一组 on/off 或 true/false 值，那么它就是一个位图。例如，Domain 对象类中的 FileMap 属性包含多个 on/off 设置：

GET https://dphost.com:5554/mgmt/config/default/Domain/my-testing-domain

如清单 23 所示， FileMap 属性包含 6 个具有 on/off 设置的条目。

清单 23. 包含位图属性的响应

{    "_links": {      "self": {        "href": "/mgmt/config/default/Domain/my-testing-domain"     },      "doc": {        "href": "/mgmt/docs/config/Domain"     }    },    "Domain": {      "name": "my-testing-domain",      "mAdminState": "enabled",      "FileMap": {        "CopyFrom": "on",        "CopyTo": "on",        "Delete": "on",        "Display": "on",        "Exec": "on",        "Subdir": "on"     },      "ConfigMode": "local",      "ImportFormat": "ZIP",      "LocalIPRewrite": "on",      "MaxChkpoints": 3    }

位图属性上的属性更新具有不同的行为：

仅更新位图属性中选定的位，会自动将所有未指定的剩余位设置为 "off"。
如果请求载荷中存在位图属性值，但该值是空的，那么所有属性位都会被重置为其默认值。
如果包含位图属性的对象被更新，而且请求载荷中省略了位图属性，那么位图属性值会保持不变。

下面几节中演示了每种行为类型的请求和响应示例。

设置部分位图属性

使用包含位图的不完整规范的载荷来更新一个包含位图属性的配置对象时，省略的位被自动设置为 "off" 设置。清单 24 演示了此概念，将一个 Domain 对象类的 FileMap 属性修改为一个仅包含 FileMap 属性的 Exec 位的载荷。

清单 24. 包含部分位图更新的载荷

{    "Domain": {      "name": "my-testing-domain",      "mAdminState": "enabled",      "FileMap": {        "Exec": "off"     },      "ConfigMode": "local",      "ImportFormat": "XML",      "LocalIPRewrite": "off",      "MaxChkpoints": 5    }   }

发送对象更新请求：

PUT https://dphost.com:5554/mgmt/config/default/Domain/my-testing-domain

清单 25 中的对象配置显示了结果，其中省略的条目被设置为 "off"。

清单 25. 对位图属性执行部分更新的结果

{    "_links": {      "self": {        "href": "/mgmt/config/default/Domain/my-testing-domain"     },      "doc": {        "href": "/mgmt/docs/config/Domain"     }    },    "Domain": {      "name": "my-testing-domain",      "mAdminState": "enabled",      "FileMap": {        "CopyFrom": "off",        "CopyTo": "off",        "Delete": "off",        "Display": "off",        "Exec": "off",        "Subdir": "off"     },      "ConfigMode": "local",      "ImportFormat": "XML",      "LocalIPRewrite": "off",      "MaxChkpoints": 5    }   }

设置空位图属性

使用包含一个空位图的载荷来更新一个包含位图属性的配置对象时，所有位会被自动重置为其默认值。清单 26 演示了此概念。在此清单中，Domain 对象类的 FileMap 属性被修改为一个包含空 FileMap 属性的载荷。 FileMap 属性中的位的默认值为 "on"。

清单 26. 包含空位图更新的载荷

{    "Domain": {      "name": "my-testing-domain",      "mAdminState": "enabled",      "FileMap": {      },      "ConfigMode": "local",      "ImportFormat": "ZIP",      "LocalIPRewrite": "on",      "MaxChkpoints": 3    }   }

发送对象更新请求（如设置部分位图属性中所示）会得到清单 27 中的对象配置，其中所有位图条目都被重置为其默认值 "on"。

清单 27. 对位图属性执行空更新的结果

{    "_links": {      "self": {        "href": "/mgmt/config/default/Domain/my-testing-domain"     },      "doc": {        "href": "/mgmt/docs/config/Domain"     }    },    "Domain": {      "name": "my-testing-domain",      "mAdminState": "enabled",      "FileMap": {        "CopyFrom": "on",        "CopyTo": "on",        "Delete": "on",        "Display": "on",        "Exec": "on",        "Subdir": "on"     },      "ConfigMode": "local",      "ImportFormat": "ZIP",      "LocalIPRewrite": "on",      "MaxChkpoints": 3    }

省略位图属性

使用一个省略了位图属性的载荷更新一个包含位图属性的配置对象时，所有位都会保持不变。清单 28 演示了此概念，将 Domain 对象类修改为一个完全省略了 FileMap 属性的载荷。

清单 28. 省略了位图属性的载荷

{    "Domain": {      "name": "my-testing-domain",      "mAdminState": "disabled",      "ConfigMode": "local",      "ImportFormat": "XML",      "LocalIPRewrite": "on",      "MaxChkpoints": 5    }   }

发送对象更新请求（如设置部分位图属性中所示）会得到清单 29 中的对象配置。其中，位图条目自上次更新以来保持不变，其他属性的值更新为载荷中的值。

清单 29. 省略位图属性的结果

{    "_links": {      "self": {        "href": "/mgmt/config/default/Domain/my-testing-domain"     },      "doc": {        "href": "/mgmt/docs/config/Domain"     }    },    "Domain": {      "name": "my-testing-domain",      "mAdminState": "disabled",      "FileMap": {        "CopyFrom": "on",        "CopyTo": "on",        "Delete": "on",        "Display": "on",        "Exec": "on",        "Subdir": "on"     },      "ConfigMode": "local",      "ImportFormat": "XML",      "LocalIPRewrite": "on",      "MaxChkpoints": 5    }   }

回页首

结束语

在本教程中，我们了解了如何通过 IBM DataPower Gateway 设备的 REST 管理接口执行配置管理。学习了如何检索、修改和删除设备上的现有配置，以及如何构造有效的请求载荷来创建配置。还了解了配置对象的列表属性和位图属性的行为。作为本教程系列的延续，第 3 部分将解释 DataPower Gateway 设备上的文件和目录管理。

回页首