第八章 创建和使用策略

本主题介绍如何在 IRIS 中使用 WS-Policy 支持。WS-Policy 使您能够指定要使用或预期的 标头。它还使能够指定 标头和 的使用（在创建 服务和 客户端中描述）。可以在单独的类中创建策略，而不是直接编辑 服务或 客户端。在大多数情况下，不需要进行低级编程。

概述

在 中， 服务或客户端的策略（或策略集合）包含在单独的配置类中，即 %SOAP.Configuration的子类。编译该类时，策略生效。

通常不需要编码。但是，在某些情况下，可以通过编程指定详细信息，而不是将该元素硬编码到策略中。

配置类的作用

当编译配置类时， 服务或客户端的未来操作将受到如下影响：

• Web 服务或客户端根据策略的详细信息在出站消息中包含额外的标头元素。
• Web 服务或客户端根据策略验证传入的 SOAP 消息。这包括在适当的情况下解密传入的消息。
• 如果合适， 服务或客户端可以选择加密传出消息。
• 对于 服务， 会自动受到影响。具体来说，会添加 元素，并且命名空间声明包括以下内容：

xmlns:wsp="http://www.w3.org/ns/ws-policy"

重要提示：如果配置类映射到多个命名空间，则必须在每个命名空间中对其进行编译。

与 、

第七章 设置和其他常见活动 - 从入站消息中检索证书

从入站消息中检索证书

如果收到已进行数字签名的 SOAP 消息，则相关证书可在 %SYS.X509Credentials 的实例中找到。可以检索该证书。操作方法如下：

1. 首先通过 Web 服务或 Web 客户端的 SecurityIn 属性访问 标头元素。这将返回 的实例。
2. 然后执行以下操作之一：

• 在实例中访问 的 属性，该属性引用安全标头元素中的第一个 元素。
• 在实例中使用 的 方法访问实例中 的第一个 元素。

无论哪种情况，结果都是在包含数字签名的 %XML.Security.Signature 实例。

3. 访问签名对象的 X509Credentials 属性。
4. 检查返回对象的类型，看它是否是 %SYS.X509Credentials 的实例。

 if $CLASSNAME(credset)'="%SYS.X509Credentials" {set credset=""}

如果入站消息包含已签名的 SAML 断言，则 X509Credentials 属性是某个其他类的实例，不能用于访问实例中的。

示例：

第六章 设置和其他常见活动 - 编辑 IRIS 凭证集

编辑 IRIS 凭证集

创建 IRIS 凭证集后，可以按如下方式编辑它：

1. 在管理门户中，选择系统管理 > 安全 > X.509 凭证。
2. 在凭证集表中，别名列的值用作标识符。对于要编辑的凭证集，请单击编辑。
3. 根据需要进行编辑。有关这些字段的信息，请参阅上一节。
4. 单击“保存”以保存更改。

无法更改凭证集的别名或证书；也无法添加、更改或删除关联的私钥。要进行此类更改，请创建新的凭证集。

通过编程方式检索凭证集

执行加密或签名时，必须指定要使用的证书。为此，可以选择 IRIS 凭证集。

当手动创建 WS-Security 标头时，必须以编程方式检索凭据集并使用它。

作为参考，本节讨论以下常见活动：

• 如何检索存储的凭证集
• 如何从入站消息中检索凭证集

检索存储的凭证集

要检索 的实例，请调用 类方法。此方法返回包含证书和其他信息的 凭证集。例如：

 set credset=##class(%SYS.X509Credentials).GetByAlias(alias,password)

• alias 是证书的别名。
• pwd 是私钥密码；这仅适用于拥有证书的情况。仅当关联的私钥已加密且您在加载私钥文件时未加载密码时，才需要此密码。

如果不拥有该证书，则无法以任何形式访问私钥。

如果未指定密码参数，实例中的 将无法访问私钥，因此只能用于加密。

第五章 设置和其他常见活动 - 创建 IRIS 凭证集

创建 IRIS 凭证集

要创建 IRIS 凭证集：

1. 获取以下文件：

• 个人 X.509 证书，采用 PEM 编码的 X.509 格式。

这可以是自己的证书，也可以是从希望与之交换 SOAP 消息的实体获取的证书。

• （可选）关联的私钥，采用 编码的 格式。

这仅适用于拥有证书的情况。如果不想签署出站消息，则无需加载私钥文件。

• （可选）包含根证书的文件，即 PEM 编码格式的受信任的 CA X.509 证书，可与此凭证集一起使用。

有关创建这些文件的信息超出了本文档的范围。

2. 在管理门户中，选择系统管理 > 安全 > X.509 凭证。
3. 单击“创建新凭证”。
4. 指定以下值：

• — 指定一个唯一的、区分大小写的字符串来标识此凭证集。此属性是必需的。
• 包含 证书的文件 — 单击浏览...并导航到证书文件。此属性是必需的。
• 包含相关私钥的文件 — 单击浏览...并导航到该文件。
• 私钥密码和私钥密码（确认）— 指定私钥的密码。如果不指定密码，则在检索凭证集时必须提供密码。

仅当为包含关联私钥的文件指定值时才会显示这些字段。

• 包含受信任的证书颁发机构 证书的文件 — 此凭证集信任的任何 的 证书的路径和文件名。证书必须采用 格式。路径可以指定为绝对路径或相对于管理器目录的路径。

第四章 设置和其他常见活动

作为参考，本主题介绍了用于保护 Web 服务的常见活动。

执行设置任务

对于大多数与 SOAP 安全相关的任务，必须首先执行以下任务：

• 提供可信证书供 IRIS 使用
• 创建 IRIS 凭证集

这些任务也是使用 XML 工具中描述的某些任务的先决条件。

可能还需要创建 配置。有关信息，请参阅 指南。

为 IRIS 提供可信证书

使用其自己的可信证书集合来验证入站 消息（或 XML 文档）中的用户证书和签名。在加密出站 消息中的内容或加密 文档时，它也会使用这些证书和签名。此集合可供此 安装的所有命名空间使用。要创建此集合，请创建以下两个文件并将它们放在系统管理器的目录中：

• iris.cer — 包含根证书，即 PEM 编码格式的受信任 CA X.509 证书。如果想在 中使用任何 或 功能，则需要此文件。
• — 包含 编码格式的 证书撤销列表。此文件是可选的。

请注意，可以使用特定的 凭证集作为备用根证书；请参阅下一节。

有关创建这些文件的信息超出了本文档的范围。有关 （指定证书和证书撤销列表的内容）的信息，请参阅 。有关 编码（一种文件格式）的信息，请参阅 。

注意：对于任何生产用途，请务必从可信来源获取证书，因为这些证书是信任所有其他证书的基础。

此集合不用于 。

创建和编辑 凭证集

本节介绍如何创建和编辑

第三章 使用 SOAP 保护 Web 服务 - IRIS 中的 WS-Policy 支持

IRIS 中的 WS-Policy 支持

支持 WS-Policy 1.2 (https://www.w3.org/Submission/WS-Policy/) 和 WS-Policy 1.5 (https://www.w3.org/TR/ws-policy) 框架以及相关的特定策略类型：

• WS-SecurityPolicy 1.1 (http://www.oasis-open.org/committees/download.php/16569/)

• WS-SecurityPolicy 1.2 (http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.2/ws-securitypolicy.html)

• Web Services Addressing 1.0 - Metadata (https://www.w3.org/TR/ws-addr-metadata)

• Web Services Addressing 1.0 - (https://www.w3.org/TR/ws-addr-wsdl)

• WS-MTOMPolicy (https://www.w3.org/Submission/WS-MTOMPolicy/

第二章 使用 SOAP 保护 Web 服务 - WS-Security 标头简介

WS-Security 标头简介

SOAP 消息在 WS-Security 标头元素（SOAP 元素的 子元素）中携带安全元素。以下示例显示了一些可能的组件：

这些元素如下：

• 时间戳标记 () 包含 和 元素，它们指定此消息有效的时间范围。严格来说，时间戳不是安全元素。但是，如果时间戳已签名，则可以使用它来避免重放攻击。
• 二进制安全令牌 () 是二进制编码的令牌，其中包含使接收者能够验证签名或解密加密元素的信息。您可以将其与签名元素、加密元素和断言元素一起使用。
• 用户名令牌 () 使 Web 客户端能够登录 Web 服务。它包含 Web 服务所需的用户名和密码；默认情况下，这些内容以`文形式包含。有多种保护密码的选项。
• 断言元素 () 包含创建的 SAML 断言。断言可以是签名的，也可以是未签名的。

断言元素可以包含主题确认元素 ()。此元素可以使用 方法或 Sender-vouches 方法。在前一种情况下，断言携带可用于其他目的的密钥材料。

• 加密密钥元素 () 包含密钥、指定加密方法，并包含其他此类信息。此元素描述消息的加密方式。请参阅加密概述。
• 签名元素 () 对消息的各个部分进行签名。

第一章 使用 SOAP 保护 Web 服务

IRIS 支持 WS-Security、WS-Policy、 和 规范的部分内容，这些规范描述了如何为 服务和 客户端添加安全性。本主题总结了这些工具并列出了支持的标准。

如果 客户端使用需要身份验证的 服务，并且有特殊原因，则可以使用较旧的 WS-Security 登录功能。请参阅使用 登录功能。

中与 安全相关的工具

IRIS 提供以下与 服务和 Web 客户端安全相关的工具：

• 能够为 IRIS 提供可信证书，以用于验证入站消息中收到的证书和签名。
• 能够表示 X.509 证书。可以在 数据库中存储拥有的证书以及将与之通信的实体的证书。对于拥有的证书，如果需要签署出站消息，还可以存储相应的私钥。

在 数据库中， 证书包含在 凭证集中，具体来说，包含在 实例中。可以使用此类的方法将证书（以及可选的关联私钥文件，如果适用）加载到数据库中。可以直接执行这些方法，也可以使用管理门户。

可以指定谁拥有凭证集以及谁可以使用它。

类还提供了通过别名、指纹、主题密钥标识符等访问证书的方法。出于安全原因，无法使用常规对象和 技术访问 %SYS.X509Credentials类。

• 支持 （安全套接字层）和 （传输层安全性）。可以使用管理门户定义 配置，然后可以使用这些配置通过

第十章 指定 SAX 解析器的标志

指定 SAX 解析器的标志

当 Web 客户端调用 Web 服务时，它会在内部使用 SAX 解析器，这是 附带的第三方产品。可以设置 客户端的 属性，以设置解析器要使用的标志。

要使用 登录功能：

1. 确保在 Web 客户端和托管 Web 服务的 服务器之间使用 。 标头以明文形式发送，因此除非使用 ，否则此技术并不安全。请参阅将客户端配置为使用 。
2. 调用 客户端的 方法。此方法接受用户名和密码，生成带有明文密码的 WS-Security 用户名令牌，并将 标头添加到 请求。
3. 调用 方法。

此技术仅将安全令牌添加到下一条 消息中。

使用 身份验证

某些 服务需要 身份验证，而不是使用 （在“保护 服务”中进行了描述）。对于这些 服务， 数据平台支持以下 身份验证方案：

1. 协商（ 和 Kerberos，符合 和 ）
2. （ 管理器身份验证协议）
3. Basic 基本（ 中描述的基本访问身份验证）

请注意，在

第九章 从 Web 客户端指定自定义传输

从 Web 客户端指定自定义传输

默认情况下，如果使用 Web 客户端，Web 客户端将使用 HTTP 将 消息传输到 服务并接收响应。可以定义并使用自己的传输类。

背景

为了与其使用的 服务进行通信， 客户端需要一个传输类。传输类包含与通信相关的参数、属性和方法。整体通信工作方式如下：

1. 运行 Web 客户端代理方法时，Web 客户端实例会检查其 Transport 属性的值。

如果此属性为空，则 客户端实例将使用自身作为传输类实例。可以将 Transport 属性设置为其他合适类的实例（如果已定义此类）。

2. Web 客户端实例执行传输类的 DoSOAPRequest() 方法，并传递以下参数：

a. 客户端类的 。

b. 指定 操作的字符串。

c. 包含以 编码的请求的流。

d. （通过引用）包含响应的流。

3. 客户端实例检查结果的状态并采取相应行动。

对于 HTTP 传输， 方法包括以下逻辑：

1. 创建请求对象（%Net.HttpRequest 的实例）并设置其属性。此处，该方法使用 Web 客户端实例的属性值，特别是 和其他与 相关的属性。
2. 遍历 请求中的标头并初始化请求对象中的标头。
3. 执行请求对象的方法，这是一个适合传输的动作。
4. 获取响应并返回。

重要提示：请勿直接使用 的 方法。

第八章 指定自定义 HTTP 请求

默认情况下，Web 客户端使用 HTTP 将 SOAP 消息传输到 服务并接收响应。 客户端会自动创建并发送 请求，但可以创建自定义 请求。为此，请使用以下步骤：

1. 在创建 %Net.HttpReques 的实例并根据需要设置属性。有关此类的信息，请参阅使用 Internet 实用程序或 类文档。
2. 将 客户端的 属性设置为等于此实例。

如果希望在同一会话中支持对 SOAP 服务的多次调用，这尤其有用。默认情况下， 客户端不支持使用同一会话对 SOAP 服务进行多次调用。要解决此问题，创建一个新的 实例，并将其用作 客户端的 属性。此更改强制对所有调用重复使用相同的 请求，这将在对下一个请求的响应中返回所有 。

自定义 客户端的回调

可以通过覆盖其回调方法来定制 客户端的行为：

%OnSOAPRequest()

Method %OnSOAPRequest(mode As %String, 
                      client As %SOAP.WebClient,  
                      action As %String,  
                      oneWay As %Boolean,  
                      method As %String,  
                      requestStream As %BinaryStream)

第七章 解析时使用进程私有全局变量

默认情况下， Web 客户端在解析请求或响应时通常使用本地数组内存。可以强制它改用进程私有全局变量；这使 Web 客户端能够处理非常大的消息。

为此，请指定 Web 服务类的 参数，如下所示：

Parameter USEPPGHANDLER = 1;

如果此参数为 ，则 Web 客户端在解析请求或响应时始终使用进程私有全局变量。如果此参数为 0，则 客户端始终使用本地数组内存来实现这些目的。如果未设置此参数，则 客户端使用默认值，通常是本地数组内存。

可以在运行时覆盖此参数。为此，请设置 客户端实例的 属性。

创建自定义 消息

在特殊情况下，可能希望 客户端发送自定义 消息。基本要求如下：

1. 创建 %SOAP.WebRequest的子类并设置其 LOCATION 参数或 Location 属性。
2. 在此子类中，创建一个方法来发送 消息。此方法必须创建 的实例，并将要发送的 消息放入其中。有责任确保消息格式正确。
3. 该方法接下来必须调用 方法：

• 是一个字符串，它给出了要执行的 SOAP 操作的名称。
• 是一个真/假标志，控制消息是否是单向的。
• Request是

[toc]

第六章 定义单向 Web 方法

通常，当 Web 客户端调用 Web 服务时，会返回 SOAP 消息，即使该方法没有返回类型并且在 数据平台中执行时不返回任何内容。

在极少数情况下，可能需要将 方法定义为单向的。此类方法不得返回任何值，并且消息不需要 响应。

注意：通常不应使用单向方法。请求-响应对更为常见、更受支持且更受期待 — 即使对于没有返回类型的方法也是如此。

要定义单向 Web 方法，请将该方法的返回类型定义为 。WSDL 未定义此 方法的输出，并且 服务不返回 消息。

向二进制数据添加换行符

可以使 服务在新选项卡中为 类型属性中为 类型属性添加自动换行符。为此，请执行以下操作之一：

• 在 Web 服务类中将 BASE64LINEBREAKS 参数设置为 。
• 对于 服务类实例，将 属性设置为 。此属性的值优先于 参数设置的值。

对于参数和属性，默认值为 0；默认情况下， 服务不包括新选项卡中 类型属性或中 类型的属性的自动换行符。

向 消息添加字节顺序标记

默认情况下， 客户端发送的消息不以 （字节顺序标记）开头。

通常不需要 ，因为消息以 编码，不存在字节顺序问题。但是，在某些情况下，在 消息中包含 是必要的或可取的；此 仅表示消息是 。

要将 添加到

第五章 引用 SOAP 操作（仅限 SOAP 1.1）

引用 SOAP 操作（仅限 SOAP 1.1）

在 SOAP 1.1 请求消息中， 标头包含如下 SOAPAction 行：

POST /csp/gsop/GSOP.DivideWS.cls HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; InterSystems IRIS;)
Host: localhost:8080
Connection: Close
Accept-Encoding: gzip
SOAPAction: http://www.mynamespace.org/GSOAP.DivideWS.Divide
Content-Length: 397
Content-Type: text/xml; charset=UTF-8

...

默认情况下，的值不带引号。要将此值放在引号中，请在 Web 客户端类中将 指定为 1。然后请求消息的 标头将如下所示：

POST /csp/gsop/GSOP.DivideWS.cls HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; InterSystems IRIS;)
Host: localhost:8080
Connection: Close
Accept-Encoding: gzip
SOAPAction: "http://www.mynamespace.org/GSOAP.DivideWS.Divide"
Content-Length: 397
Content-Type: text/xml; charset=UTF-8

...

第四章 控制编码格式的内联引用的使用

控制编码格式的内联引用的使用

采用编码格式，任何对象值属性都作为引用包含在内，并且引用的对象作为单独的元素写在 SOAP 消息中。

要以内联方式写入编码对象，请在 Web 客户端中将 REFERENCESINLINE 参数或 ReferencesInline 属性指定为 `1。属性优先于参数。

指定信封前缀

默认情况下， 客户端在其发送的 消息的信封中使用前缀 SOAP-ENV。可以指定不同的前缀。为此，请设置 客户端类的 参数。例如，如果将此参数设置为 ，则 客户端会在其消息中包含此前缀，而不是 。

将命名空间声明添加到 信封

要将命名空间声明添加到给定 客户端返回的 响应的 信封（元素）中，请在调用 方法之前调用 客户端的 方法。此方法具有以下签名：

其中：

• namespace 是需要添加的命名空间。
• prefix 是用于此命名空间的可选前缀。如果省略此参数，则会生成前缀。
• schemaLocation

第三章 控制 xsi:type 属性的使用

控制 xsi:type 属性的使用

默认情况下， SOAP 消息仅包含顶级类型的 xsi:type属性。例如：

<?xml version="1.0" encoding="UTF-8" ?>
...
<types:GetPersonResponse>
<GetPersonResult href="#id1" />
</types:GetPersonResponse>
<types:Person id="id1" xsi:type="types:Person">
<Name>Yeats,Clint C.</Name>
<DOB>1944-12-04</DOB>
</types:Person>  
...

在这些示例中，已添加换行符以提高可读性。要将此属性用于 消息中的所有类型，请执行以下操作之一：

• 在 Web 客户端实例中将 OutputTypeAttribute 属性设置为等于 1。
• 在 客户端类中将 参数设置为等于 1。

相同的输出将如下所示：

<?xml version="1.0" encoding="UTF-8" ?>
...
<types:GetPersonResponse>
<GetPersonResult href="#id1" />
</types:GetPersonResponse>
<types:Person id="id1" xsi:type="types:Person">
<Name xsi:type="s:string">Yeats,Clint C.</Name>
<DOB xsi:type="s:date">1944-12-04</DOB>
</types:Person> 
...

第二章 使用代理服务器

使用代理服务器

Web 客户端可以通过代理服务器与 Web 服务通信。要进行设置，请指定 Web 客户端实例的属性以指示要使用的代理服务器。这些属性如下：

HttpProxyServer

指定要使用的代理服务器的主机名。如果此属性不为空，则 请求将定向到此计算机。

HttpProxyPort

指定代理服务器上要连接的端口。

HttpProxyHTTPS

如果使用代理服务器并且该代理服务器支持 ，则将其指定为 。

请注意，如果使用 ，则还必须将客户端的 属性设置为 SSL/TLS 配置的名称；有关更多详细信息，请参阅配置客户端以使用 。

如果 客户端需要向代理服务器验证自身身份，请将其指定为所需的 标头字段。

HttpProxyTunnel

如果 客户端应通过代理建立到目标 服务器的隧道，请将其指定为 。如果为 ，请求将使用 命令建立隧道。代理服务器的地址取自 和 属性。如果端点 具有 协议，则一旦建立隧道， 就会协商 连接。在这种情况下， 属性将被忽略，因为隧道与目标系统建立了直接连接。

设置 HTTP 标头

如果需要进一步控制 客户端发送的 标头，则可以使用 的以下方法：

向 请求添加标头。请注意，、 和 标头是实体主体的一部分，而不是 主标头。无法设置 标头，因为它是只读的。也无法设置

第一章 修改 Web 客户端

修改 Web 客户端

生成 Web 客户端类后，通常不需要编辑该类。相反，需要编写代码来创建该类的实例并提供客户端错误处理。本主题讨论了微调 Web 客户端的各种方法，可以通过修改 Web 客户端实例或（不太常见）修改生成的类来实现。

注意：不要创建生成的 客户端类的子类。编译器不会生成正常运行所需的支持类，因此子类将无法使用。

禁用 客户端的 Keep-Alive

默认情况下，如果重复使用 Web 客户端实例来发送多条请求消息， 会在一次 传输中发送所有消息（使用 保持活动连接）。具体来说， 保持 套接字打开，这样 就无需关闭并重新打开它。要禁用此保持活动行为，请执行以下操作之一：

• 终止 Web 客户端实例并创建并使用一个新的。
• 发送第一条消息后，将客户端的 HttpRequest.SocketTimeout 属性设置为 。例如：

Set client.HttpRequest.SocketTimeout=0

注意：如果正在使用 并使用 与 Web 服务通信，请不要禁用保持活动。有关 的信息，请参阅保护 服务。

控制空字符串参数的形式

通常，如果省略参数， 客户端会省略其发送的 消息中的相应元素。要更改此设置，请在 客户端类中将 参数设置为 ；在这种情况下，

[toc]

第十二章 在 Web 服务中定义自定义处理 - 实现 ProcessBody()

实现 ProcessBody()

ProcessBody() 方法具有以下签名：

method ProcessBody(action As %String, requestBody As %CharacterStream, 
                   ByRef responseBody As %CharacterStream) as %Boolean

其中：

• action 是入站消息中指定的 SOAP 操作。
• requestBody 是 的一个实例，包含 元素。该流包含 XMLXML
• responseBody%Library.CharacterStream

Web

 if action["action1" { 
  //details
 }

2. 使用 requestBodyRead()

 set in1="<echoString xmlns=""http://soapinterop.org/xsd""><inputString>"
 set in2="</inputString></echoString>"  
 set contents=$extract(request,$length(in1)+1,*-$length(in2))

6. 1

第九章 使用进程私有全局变量来支持非常大的消息

使用进程私有全局变量来支持非常大的消息

默认情况下、 Web 服务在解析请求或响应时通常使用本地数组内存。可以强制它改用进程私有全局变量；这使 Web 服务能够处理非常大的消息。

为此，请指定 Web 服务类的 参数，如下所示：

Parameter USEPPGHANDLER = 1;

如果此参数为 ，则 Web 服务在解析请求或响应时始终使用进程私有全局变量。如果此参数为 0，则 服务始终使用本地数组内存来实现这些目的。如果未设置此参数，则 Web 服务使用默认值，通常是本地数组内存。

自定义 服务的回调

可以通过覆盖其回调方法来定制 服务的行为：

如果没有安全错误，则在 服务收到请求消息时调用；如果出现安全错误，则不会调用此回调。系统在执行安全处理、检查信封是否有错误以及处理 标头中指定的操作（如果有）后调用此回调。此回调对于记录原始 请求等任务很有用。

此方法具有以下签名：

其中：

• mode 指定 SOAP 请求的类型。该类型为“SOAP”或。
• 包含 标头的值。
• 请求以流的形式包含 请求消息。

此方法可以使用对象 ，它是 实例。在此对象中：

• 属性包含原始请求消息。
• 实例方法使能够检索单个 部分（如果这是一个 请求）。

此方法还可以使用 服务实例的属性。初始化期间设置以下属性：

第五章 控制 xsi:type 属性的使用

控制 xsi:type 属性的使用

默认情况下， SOAP 消息仅包含顶级类型的 xsi:type 属性。例如：

<?xml version="1.0" encoding="UTF-8" ?>
...
<types:GetPersonResponse>
<GetPersonResult href="#id1" />
</types:GetPersonResponse>
<types:Person id="id1" xsi:type="types:Person">
<Name>Yeats,Clint C.</Name>
<DOB>1944-12-04</DOB>
</types:Person>  
...

在这些示例中，已添加换行符以提高可读性。要将此属性用于 消息中的所有类型，请将 OUTPUTTYPEATTRIBUTE 参数或 OutputTypeAttribute 属性设置为 。相同的输出将如下所示：

<?xml version="1.0" encoding="UTF-8" ?>
...
<types:GetPersonResponse>
<GetPersonResult href="#id1" />
</types:GetPersonResponse>
<types:Person id="id1" xsi:type="types:Person">
<Name xsi:type="s:string">Yeats,Clint C.</Name>
<DOB xsi:type="s:date">1944-12-04</DOB>
</types:Person> 
...

第四章 覆盖 HTTP SOAP 操作和请求消息名称

覆盖 HTTP SOAP 操作和请求消息名称

当通过 HTTP 调用 Web 方法时，HTTP 标头必须包含 操作，该操作是指示 请求意图的 。对于 ， 操作作为 标头包含在内。对于 ，它包含在 标头中。

操作指示 请求的意图。该值是一个标识意图的 URI；它通常用于路由入站 消息。例如，防火墙可以使用此标头适当地过滤 中的 请求消息。

对于 服务中的 方法，SOAPAction HTTP 标头默认具有以下形式（对于 ）：

SOAPAction: NAMESPACE/Package.Class.Method

其中 是 服务的 参数的值， 是用作 方法的方法的名称。例如：

SOAPAction: http://www.myapp.org/GSOAP.WebService.GetPerson

要覆盖此设置，请在 方法的定义中为 方法关键字指定一个值。指定一个带引号的字符串，表示 请求的意图。在典型情况下， 服务中的每个 方法都会为 指定一个唯一值（如果有）。

如果 在该 服务中不唯一，则每个方法都必须具有唯一的 方法关键字值。此关键字指定请求消息的 主体中的顶部元素的名称。请注意， 仅对包装的文档/文字消息有效。

指定元素是否符合条件

第七章 使用 SQL Search - 同义词表

同义词表

要实现同义词表，请将该表定义为扩展 iFind.Synonym 抽象类的持久类。

此类定义了两个属性：FromTerm 和 ToTerm。一对 FromTerm 和 属性将 定义为 的同义词。如果查询包含 ， 搜索将使用 来扩展查询。

该查询使用此类的 方法根据查询词在同义词表中搜索同义词。

在查询执行期间， 搜索会检查单个单词单元或位置搜索短语是否存在任何同义词。例如，在同义词表中定义了两个同义词对（“persons”、“people”）和（“walk”、“run”）。对短语执行 搜索查询。如果同义词表与查询关联，则 搜索不仅返回与原始查询匹配的文档，还返回与以下任一查询匹配的文档：和。

但是，如果 字符串为 ，则不会发生查询扩展，因为 搜索不会扩展位置短语搜索中的任何单词。位置短语本身是查询扩展的最小单位。但是，如果定义一个同义词对，如 (、)， 搜索会将查询扩展为。如果 包含多个单词， 搜索会将其视为位置短语。 可以是任何有效的位置短语；它可以包含 或 通配符。

注意：同义词表不能与正则表达式搜索 () 一起使用。

高亮

可以使用 语法突出显示返回文本中的单词。

第十六章 调用Callout Library函数

Callout 库是一个共享库（DLL 或 SO 文件），其中包含 接口的挂钩，允许各种 $ZF 函数在运行时加载它并调用其函数。 接口提供了四种不同的接口，可用于在运行时加载 库并从该库调用函数。这些接口的主要区别在于如何识别库并将其加载到内存中：

• 使用 $ZF() 访问 iriszf 标注库描述了如何使用名为 的特殊共享库。当该库可用时，可以通过 形式的调用来访问其函数，而无需事先加载该库或指定库名称。
• 使用 进行简单库函数调用描述了如何通过指定库文件路径和函数名来加载库并调用函数。它使用简单，但虚拟内存中一次只能有一个库。与其他接口不同，它在调用库函数之前不需要任何初始化。
• 使用 通过系统 访问库描述了一种可用于一次有效维护和访问多个库的接口。可以同时加载和使用多个库，每个库所需的处理开销比 $ZF(-3) 少得多。内存中的库由加载库时生成的系统定义的 来标识。
• 使用 按用户索引访问库描述了处理大量标注库的最有效接口。该接口通过定义的索引表提供对库的访问。该索引可供 实例中的所有进程使用，并且多个库可以同时位于内存中。每个索引库都被赋予一个唯一的、用户定义的索引号，并且可以在运行时定义和修改索引表。当库文件被重命名或重新定位时，与给定库

第十五章 创建Callout Library - 处理 UNIX 信号处理错误

处理 UNIX 信号处理错误

在 UNIX 及相关操作系统下运行时，如果进程收到信号，某些系统调用可能会失败，最常见的是打开、读取、写入、关闭、ioctl 和暂停。如果函数使用任何这些系统调用，代码必须能够区分真正的错误、Ctrl-C 和应重新启动的调用。

以下函数允许检查异步事件并在 中设置新的警报处理程序。函数声明包含在 中：

sigrtclr()

— 清除重试标志。应在使用 sigrtchk() 之前调用一次。

dzfalarm()

— 建立新的 `SIGALRM 处理程序。

进入 时，会自动保存先前的处理程序。退出时会自动恢复。用户程序不应改变任何其他信号的处理。

int sigrtchk(); — 检查异步事件。每当以下系统调用之一失败时就应该调用 或进程收到信号时失败的任何调用。它返回一个代码，指示用户应采取的操作：

• -1 — 不是信号。检查 I/O 错误。查看 errno 变量的内容。
• — 其他信号。从中断点重新开始操作。
• — 。使用 退出 $。这些信号被适当地捕获。

用于控制某些设备的典型 函数将使用类似于以下伪代码的逻辑：

如果进程收到信号， 系统调用可能会失败。通常这种情况不是错误，应该重新启动操作。

第十一章 创建Callout Library - 使用 J 链接类型传递标准计数字符串

使用 J 链接类型传递标准计数字符串

iris-callin.h 头文件定义了计数字符串结构 IRIS_EXSTR，表示标准 IRIS 字符串。

百讲知识点索引

简介

• B站已更新截止到2023.12.31之前的所有百讲课程，总计261讲。
• 什么是百讲？百讲是一个主要介绍IRIS、编程知识的免费课程。
• 课程的特点是，将每一个知识点，都会用示例演示出来、了解原理，而不是仅仅告诉有这个功能。
• 每周一期，每期会请到有多年开发经验的老师来给大家讲解课程。
• 百讲观看地址：https://www.bilibili.

第七章 创建Callout Library - 创建 ZFEntry 表

创建 ZFEntry 表

每个 Callout 库必须定义一个 ZFEntry 表，该表允许 IRIS 加载和访问 函数。 表由以 开头、以 结尾的宏代码块生成。在这两个宏之间，必须为要公开的每个函数调用一次 宏。

每个 调用都采用三个参数：

   ZFENTRY(zfname,linkage,entrypoint)

其中 zfname 是用于在 调用中指定函数的字符串， 是指定如何传递参数的字符串， 是 函数的入口点名称。

要创建 库，代码必须包含 指令，该指令是一个开关，可生成用于定位库函数的内部 函数。加载 库时， 调用此函数来初始化该库，以便后续查找库函数名称。

注意： 序列号

表中条目的位置可能很重要。 和 接口（在“调用标注库函数”中描述）都通过指定表中的序列号（从 开始）来调用库函数。例如， 将通过以下调用调用 表中的第三个函数：

   x = $ZF(-6,libID,3)

其中 是库标识符， 是表中第三个条目的序列号。

注意：预编译头文件

某些编译器（例如 Microsoft Visual Studio）支持预编译头。如果使用预编译头，则 #define ZF_DLL

第六章 创建Callout Library

Callout library 库是一个共享库，其中包含自定义Callout函数和允许 IRIS使用它们的启用代码。本章描述如何创建库并在运行时访问它。

• Callout library 简介-描述如何创建和访问Callout library 。
• ZFEntry链接选项 - 提供了决定如何传递函数参数的链接选项的详细描述。
• 兼容语言和编译器-描述如何使用C以外的语言创建库。
• 运行和运行函数-描述两个可选函数，可将其设置为在加载或卸载标注库时自动运行。
• 故障排除和错误处理-列出了一些应该避免的编码实践，并描述了处理UNIX信号处理错误的特殊函数。

注:共享库和标注库的术语，共享库是指动态链接的文件(上的DLL文件或及相关操作系统上的文件)。是一个共享库，它包含到接口的钩子，允许各种函数在运行时加载和访问它。

库简介

从代码访问Callout库有几种不同的方法，但一般原则是指定库名、函数名和任何必需的参数(请参阅“调用库函数”)。例如，下面的代码调用一个简单的库函数:

从库调用函数

下面的代码在终端上执行。它加载一个名为的库，并调用一个名为的库函数，该函数将两个整数参数相加并返回总和。

库并不比调用它的代码复杂多少。它包含所有 库所需的三个元素：

1. 包含 iris-cdzf.h Callout 头文件时提供的标准代码。

第五章 使用$ZF(-100)运行程序或系统命令 - 增加权限

增加%System_Callout:USE权限

$ZF(-100)需要%System_Callout:USE权限。如果安全设置高于最小值，则可能会禁用此特权。下面的过程描述了如何在%Developer角色中启用它:

在角色中启用

1. 在“管理门户”中，选择“系统管理员>安全>角色”。
2. 在Roles页面上，单击Names列中的。
3. 在页面的选项卡上，找到%System_Callout权限并单击
4. 在“编辑资源权限”对话框中，如果尚未选中，请选中“权限使用”复选框，然后单击“确定”。

角色总是在安装 IRIS时创建，但是管理员可能不希望所有用户都可以使用它。在某些情况下，可能需要为用户提供一个角色，使可用，但不授予任何其他特权。下面的过程创建了一个只授予权限的新角色:

在新角色中启用

1. 打开Management Portal，进入System Administration > Security > Roles。

2. 在页面上，单击按钮以调出页面。

3. 填写姓名和描述:

   • Name: UseCallout
   • description:授予使用%System_CallOut资源的权限

   单击时，表单上将出现一个按钮。

4. 单击Add