通过

WCF-WebHttp 适配器

  • 项目

Microsoft BizTalk Server使用 WCF-WebHttp 适配器将消息发送到 RESTful 服务。 WCF-WebHttp 发送适配器将 HTTP 消息从 BizTalk 消息发送到服务。 接收位置将接收来自 RESTful 服务的消息。 对于 GET 和 DELETE 请求，适配器不使用任何负载。 对于 POST 和 PUT 请求，适配器将 BizTalk 消息正文部分用于 HTTP 内容/负载。

本主题演示如何使用 BizTalk 管理创建接收位置和发送端口。

创建接收位置

注意

在完成以下过程之前，必须已添加单向接收端口。 请参阅 如何创建接收端口。

  1. 在“BizTalk Server管理控制台”中，依次展开“BizTalk Server管理”、“BizTalk 组”、“应用程序”，然后展开要创建接收位置的应用程序。

  2. 在左窗格中，单击“接收端口” 节点，在右窗格中，右键单击你希望将新的接收位置与其关联的接收端口，然后单击“属性” 。

  3. 在“接收端口属性” 对话框的左窗格中，选择“接收位置” ，然后在右窗格中单击“新建” 以创建新的接收位置。

  4. 在“接收位置属性” 对话框的“传输” 部分中，从“类型” 下拉列表中选择“WCF-WebHttp” ，然后单击“配置” 以配置接收位置的传输属性。

  5. 在“ 常规 ”选项卡中，配置接收消息的 REST 接口的终结点地址。

    使用此选项 要执行此操作
    地址(URI) 必需。 指定BizTalk Server可接收基于 HTTP 的 RESTful 消息的 URI。
    终结点标识 可选。 指定终结点标识。 通过这些设置，终结点可对此接收位置进行验证。 在终结点与接收位置进行握手的过程中，Windows Communication Foundation (WCF) 基础结构将确保预期服务的标识与此元素的值保持一致。

    默认值为空字符串。
    HTTP 方法和 URL 映射 BTS 操作映射允许用户根据传入的 HTTP 方法和 URL 子路径将传入的 HTTP 请求映射到消息上下文中的 BTS 操作。 针对一组 HTTP 方法和 URI 模板对传入的 HTTP 方法和 URL 子路径进行匹配。 如果发现匹配项，适配器将使用消息中指定的值将 BTS.Operation 属性提升为 BizTalk 消息上下文。

    可以单映射或多映射格式指定 HTTP 方法到 URL 的映射。 多映射格式如下所示：

    <BtsHttpUrlMapping> <Operation Name = "DelCust" Method="DELETE" Url="/Customer/12345</BtsHttpUrlMapping>

    请注意，在上面的代码段中，客户 ID 是作为常数值 12345提供的。 但是，可能存在某些必须在运行时确定客户 ID 或任何其他查询变量的方案。 若要启用此类方案，必须在大括号 {} 内提供 URL 的变量组件。 例如，在上面的代码段中，如果将客户 ID 指定为变量，其内容将如下所示：

    <BtsHttpUrlMapping> <Operation Name = "DelCust" Method="DELETE" Url="/Customer/{ID}</BtsHttpUrlMapping>

    在这种情况下，还必须指定在运行时必须从什么位置提取变量 ID 的值。 你使用 变量映射指定该位置。

    注意
    在 URL 字段中，必须“转义”任何特殊的 XML 字符。 这可确保端口处理并保留特殊 XML 字符。 例如， & 特殊字符必须转义为 &amp;。

    发件人：
    Url=”/Customer?{ID}& group=Location”
    到:
    Url=”/Customer?{ID}&amp;group=Location”
    变量映射 如果为 HTTP 方法 URL 映射指定了变量，则必须指定变量在运行时映射到的内容。 单击“编辑” 按钮以启动“变量映射” 对话框。 在“变量” 列下，该对话框列出了你为 HTTP 方法和 URL 映射定义的变量。 在“属性名称” 字段中，你必须指定属性的名称，该属性提供的值将与变量相关联。 必须已将此属性定义/提升为解决方案的一部分。 你还必须在“属性命名空间” 字段中为该属性提供命名空间。

  6. 在“ 绑定 ”选项卡中，配置超时和与编码相关的属性。

    使用此选项 要执行此操作
    打开超时 (hh:mmss) 指定一个时间跨度值来表示为完成信道打开操作提供的时间间隔。 此值应大于或等于 System.TimeSpan.Zero。

    默认值：00:01:00

    最大值：23：59：59
    发送超时 (hh:mmss) 指定一个时间跨度值来表示为完成发送操作提供的时间间隔。 此值应大于或等于 System.TimeSpan.Zero。 如果使用请求-响应接收端口，则此值指定完成整个交互的时间跨度（即使客户端返回一条大消息）。

    默认值：00:01:00

    最大值：23：59：59
    关闭超时值 (hh:mmss) 指定一个时间跨度值来表示为完成信道关闭操作提供的时间间隔。 此值应大于或等于 System.TimeSpan.Zero。

    默认值：00:01:00

    最大值：23：59：59
    已接收消息的最大字节数 指定网络上可接收的消息的最大大小（包括标头），以字节表示。 消息的大小受为每条消息分配的内存量的限制。 你可以使用此属性来降低受拒绝服务 (DoS) 攻击的可能性。

    WCF-WebHttp 适配器在缓冲传输模式中利用 WebHttpBinding 类与终结点进行通信。 对于缓冲传输模式， WebHttpBinding.MaxBufferSize 属性始终等于此属性的值。

    默认值：65536

    最大值：2147483647
    最大并发调用数 指定针对单个服务实例的并发调用的数目。 超出此限制的调用将在队列中排队。 将此值设置为 0 等效于将其设置为 Int32.MaxValue。

    默认值为 200。

  7. 在“ 安全性 ”选项卡中，定义 WCF-WebHttp 接收位置的安全功能。

    使用此选项 要执行此操作
    安全模式 指定使用的安全类型。 有效值包括以下值：

    - 无：传输期间不保护消息。

    - 传输：使用 HTTPS 传输提供安全性。 使用 HTTPS 对 SOAP 消息进行保护。 若要使用此模式，你必须在 Microsoft Internet 信息服务 (IIS) 中设置安全套接字层 (SSL)。

    - TransportWithMessageCredential：完整性、机密性和服务身份验证由 HTTPS 传输提供。 若要使用此模式，你必须在 Microsoft Internet 信息服务 (IIS) 中设置安全套接字层 (SSL)。

    默认值为“传输” 。
    传输客户端凭据类型 指定执行客户端验证时要使用的凭据类型。 有效值包括以下值：

    - 无：传输级别不进行身份验证。

    - 基本：基本身份验证。 在基本身份验证中，用户名和密码将以明文形式通过网络发送。 你必须创建与凭据对应的域或本地用户帐户。

    - 摘要：摘要式身份验证。 此身份验证方法与基本身份验证方法相似，不同之处在于密码以哈希值的形式通过网络发送，以增强安全性。 摘要身份验证只可在域控制器运行 Windows Server 操作系统验证的域中使用。 你必须创建与客户端凭据对应的域或本地用户帐户。

    - Ntlm：NTLM 身份验证。 客户端可只发送凭据而不向此接收位置发送密码。 你必须创建与客户端凭据对应的域或本地用户帐户。

    - Windows：Windows 集成身份验证。 Windows Communication Foundation 可与 Kerberos 或 NTLM 协商，如果存在域，则首选使用 Kerberos。 如果要使用 Kerberos，则非常重要的一点是让客户端使用服务主体名称 (SPN) 标识该服务。 你必须创建与客户端凭据对应的域或本地用户帐户。

    - 证书：使用客户端证书进行客户端身份验证。 必须将用于客户端 X.509 证书的 CA 证书链安装到此计算机的“受信任根证书颁发机构”证书存储中，以便可以针对此接收位置验证客户端。

    注意传输客户端凭据类型属性必须与承载此接收位置的 IIS 虚拟目录的身份验证方案匹配。 例如，如果该属性设置为“Windows” ，则你还需为此接收位置所在的虚拟目录启用“集成 Windows 验证” 。 相似地，如果将该属性设置为“无” ，则你必须允许匿名访问此接收位置所在的虚拟目录。

    默认值为 Windows。
    服务证书 - 指纹 为此接收位置指定 X.509 证书的指纹，客户端利用该指纹验证服务。 使用“浏览” 按钮，导航到“当前用户” 位置中“我的” 存储，然后即可选择指纹。

    注意 必须将服务证书安装到承载此接收位置的接收处理程序的用户帐户的 “当前用户 ”位置。

    最小长度：0

    最大长度：40

    默认值为空字符串。

  8. 在“ 行为 ”选项卡中，指定服务级别和终结点级别的不同行为。 这些行为基于.NET Framework类。

    使用此选项 要执行此操作
    ServiceBehavior 在服务级别扩展 WCF 服务的功能。 可以添加执行不同操作的扩展，例如定义安全设置、启用调试、实现限制以及使用其他 .NET 类。

    右键单击“ ServiceBehavior”和 “添加扩展”。 该列表显示可以使用的 .NET 类。
    EndpointBehavior 扩展终结点级别接收请求的方式。 可以添加执行不同操作的扩展，例如从基于浏览器的 ASP.NET AJAX 客户端接收 HTTP 请求、指定事务的时间间隔、选择以同步或异步方式接收消息，以及使用其他 .NET 类。

    右键单击“ EndpointBehavior”和 “添加扩展”。 该列表显示可以使用的 .NET 类。

    这类似于 WCF-Custom 接收位置的行为配置。 请参阅 UI 指南和开发人员 API 命名空间参考中的 WCF 自定义传输属性对话框“接收行为”选项卡。

  9. 在“ 消息 ”选项卡中，指定 SOAP 正文 元素的数据选择。

    使用此选项 要执行此操作
    出站 HTTP 标头 指定在响应消息中标记的 HTTP 标头（如果有）。
    失败时禁用位置 指定是否禁用由于接收管道故障或路由故障而导致入站处理失败的接收位置。

    默认情况下清除此复选框。
    失败时挂起请求消息 指定是否将由于接收管道故障或路由故障而导致入站处理失败的请求消息挂起。

    默认值为清除此复选框。
    在错误中包括异常详细信息 指定发生错误时是否返回 SOAP 错误以方便进行调试。

    默认值为清除此复选框。

  10. 单击 “确定” 。

  11. 在“接收位置属性” 对话框中输入相应的值，完成对接收位置的配置，然后单击“确定” 保存设置。 有关“接收位置属性” 对话框的信息，请参阅 如何创建接收位置。

创建发送端口

  1. 在 BizTalk 管理控制台中，创建一个新的发送端口或双击某个现有发送端口以对其进行修改。 请参阅 如何创建发送端口。 配置所有发送端口选项，并在“常规”选项卡的“传输”部分中为“类型”选项指定 WCF-WebHttp。

  2. 在“ 常规 ”选项卡上的“ 传输 ”部分中，单击“ 配置 ”按钮。

  3. 在“ 常规 ”选项卡中，配置发送消息的 REST 接口的终结点地址。

    使用此选项 要执行此操作
    地址(URI) 必需。 指定发送消息所在的 REST 接口的 URI。
    终结点标识 可选。 指定终结点标识。 这些设置支持终结点对此发送端口进行验证。 在终结点与接收位置进行握手的过程中，Windows Communication Foundation (WCF) 基础结构将确保预期服务的标识与此元素的值保持一致。

    默认值为空字符串。
    HTTP 方法和 URL 映射 BTS 操作映射允许用户根据传入的 HTTP 方法和 URL 子路径将传入的 HTTP 请求映射到消息上下文中的 BTS 操作。 针对一组 HTTP 方法和 URI 模板对传入的 HTTP 方法和 URL 子路径进行匹配。 如果发现匹配项，适配器将使用消息中指定的值将 BTS.Operation 属性提升为 BizTalk 消息上下文。

    可以单映射或多映射格式指定 HTTP 方法到 URL 的映射。 多映射格式如下所示：

    BtsHttpUrlMapping> <Operation Name = "DelCust" Method="DELETE" Url="/Customer/12345" /> </BtsHttpUrlMapping>

    请注意，在上面的代码段中，客户 ID 是作为常数值 12345提供的。 但是，可能存在某些必须在运行时确定客户 ID 或任何其他查询变量的方案。 若要启用此类方案，必须在大括号 {} 内提供 URL 的变量组件。 例如，在上面的代码段中，如果将客户 ID 指定为变量，其内容将如下所示：

    <BtsHttpUrlMapping> <Operation Name = "DelCust" Method="DELETE" Url="/Customer/{ID}" /> </BtsHttpUrlMapping>

    在这种情况下，还必须指定在运行时必须从什么位置提取变量 ID 的值。 你使用 变量映射指定该位置。

    注意
    在 URL 字段中，必须“转义”任何特殊的 XML 字符。 这可确保端口处理并保留特殊 XML 字符。 例如， & 特殊字符必须转义为 &amp;。

    发件人：
    Url=”/Customer?{ID}& group=Location”
    到:
    Url=”/Customer?{ID}&amp;group=Location”
    变量映射 如果为 HTTP 方法 URL 映射指定了变量，则必须指定变量在运行时映射到的内容。 单击“编辑” 按钮以启动“变量映射” 对话框。 在“变量” 列下，该对话框列出了你为 HTTP 方法和 URL 映射定义的变量。 在“属性名称” 字段中，你必须指定属性的名称，该属性提供的值将与变量相关联。 必须已将此属性定义/提升为解决方案的一部分。 你还必须在“属性命名空间” 字段中为该属性提供命名空间。

  4. 在“ 绑定 ”选项卡中，配置超时和编码相关的属性。

    使用此选项 要执行此操作
    打开超时 (hh:mmss) 指定一个时间跨度值来表示为完成信道打开操作提供的时间间隔。 此值应大于或等于 System.TimeSpan.Zero。

    默认值：00:01:00

    最大值：23：59：59
    发送超时 (hh:mmss) 指定一个时间跨度值来表示为完成发送操作提供的时间间隔。 此值应大于或等于 System.TimeSpan.Zero。 如果使用请求-响应接收端口，则此值指定完成整个交互的时间跨度（即使客户端返回一条大消息）。

    默认值：00:01:00

    最大值：23：59：59
    关闭超时值 (hh:mmss) 指定一个时间跨度值来表示为完成信道关闭操作提供的时间间隔。 此值应大于或等于 System.TimeSpan.Zero。

    默认值：00:01:00

    最大值：23：59：59
    已接收消息的最大字节数 指定网络上可接收的消息的最大大小（包括标头），以字节表示。 消息的大小受为每条消息分配的内存量的限制。 你可以使用此属性来降低受拒绝服务 (DoS) 攻击的可能性。

    WCF-WebHttp 适配器在缓冲传输模式中利用 WebHttpBinding 类与终结点进行通信。 对于缓冲传输模式， WebHttpBinding.MaxBufferSize 属性始终等于此属性的值。

    默认值：65536

    最大值：2147483647

  5. 在“ 安全 ”选项卡中，定义 WCF-WebHttp 发送端口的安全功能。

    使用此选项 要执行此操作
    安全模式 指定使用的安全类型。 有效值包括以下值：

    - 无：传输期间不保护消息。
    - 传输：使用 HTTPS 传输提供安全性。 使用 HTTPS 对 SOAP 消息进行保护。 服务的 X.509 证书的 CA 证书链必须安装到此计算机的“受信任根证书颁发机构”证书存储区中，以便可以使用该服务的证书向发送端口验证该服务。
    - TransportWithMessageCredential：完整性、机密性和服务身份验证由 HTTPS 传输提供。 服务的 X.509 证书的 CA 证书链必须安装到此计算机的“受信任根证书颁发机构”证书存储区中，以便使用服务证书向发送端口验证该服务。 发送端口验证由 SOAP 消息安全性提供。

    默认值为“无”。
    传输客户端凭据类型 指定执行客户端验证时要使用的凭据类型。 有效值包括以下值：

    - 无：传输级别不进行身份验证。
    - 基本：基本身份验证。 在基本身份验证中，用户名和密码将以明文形式通过网络发送。 你必须创建与凭据对应的域或本地用户帐户。
    - 摘要：摘要式身份验证。 此身份验证方法与基本身份验证方法相似，不同之处在于密码以哈希值的形式通过网络发送，以增强安全性。 摘要身份验证只可在域控制器运行 Windows Server 操作系统验证的域中使用。 你必须创建与客户端凭据对应的域或本地用户帐户。
    - Ntlm：NTLM 身份验证。 客户端可只发送凭据而不向此接收位置发送密码。 你必须创建与客户端凭据对应的域或本地用户帐户。
    - Windows：Windows 集成身份验证。 Windows Communication Foundation 可与 Kerberos 或 NTLM 协商，如果存在域，则首选使用 Kerberos。 如果要使用 Kerberos，则非常重要的一点是让客户端使用服务主体名称 (SPN) 标识该服务。 你必须创建与客户端凭据对应的域或本地用户帐户。
    - 证书：使用客户端证书进行客户端身份验证。 必须将用于客户端 X.509 证书的 CA 证书链安装到此计算机的“受信任根证书颁发机构”证书存储中，以便可以针对此接收位置验证客户端。 注意：传输客户端凭据类型属性必须与承载此接收位置的 IIS 虚拟目录的身份验证方案匹配。 例如，如果该属性设置为“Windows” ，则你还需为此接收位置所在的虚拟目录启用“集成 Windows 验证” 。 相似地，如果将该属性设置为“无” ，则你必须允许匿名访问此接收位置所在的虚拟目录。

    默认值为 Windows。
    客户端证书 - 指纹 指定用于向终结点验证此发送端口的 X.509 证书的指纹。 可以通过使用“浏览”按钮导航到“当前用户”位置中的“我的商店”来选择指纹。 注意： 对于托管此发送端口的发送处理程序，必须将客户端证书安装到用户帐户的 “当前用户 ”位置。

    最小长度：0

    最大长度：40

    默认值为空字符串。
    服务证书 - 指纹 指定用于验证终结点（此发送端口要将消息发送到的终结点）的 X.509 证书的指纹。 可以使用“浏览”按钮选择导航到本地计算机位置中的“其他人员存储”的指纹。

    最小长度：0

    最大长度：40

    默认值为空字符串。
    用户名凭据 指定用于发送消息的凭据。 可以通过单击“ 编辑” 按钮来指定属性。 如果为消息客户端凭据类型选择了“用户名”选项，则必须设置凭据。

    默认值为 “不使用单一登录”。
    使用 ACS 服务标识 适用于 BizTalk Server 2013 R2 和 BizTalk Server 2013。

    选中此复选框并单击“ 编辑 ”，并提供以下值以向服务总线进行身份验证。 仅当调用服务总线相关实体的 REST 接口时，才需要这样做。

    - 访问控制服务 STS URI – 将此项设置为 https://<Namespace>-sb.accesscontrol.windows.net/，其中 <namespace> 是服务总线命名空间。
    - 颁发者名称 – 指定颁发者名称。 通常将此值设置为 owner。
    - 颁发者密钥 – 指定颁发者密钥。
    服务总线连接信息 从 2016 BizTalk Server 开始新增功能。

    选择使用服务总线命名空间的共享访问签名 (SAS) 或 访问控制 服务 (ACS) 。

    选择一个选项，然后选择 “编辑” 以输入密钥信息：

    - 共享访问签名 ：输入访问密钥名称和访问密钥。 Azure 门户中列出了这两个值。
    - 访问控制服务：输入 STS URI (https://<yourNamespace>-sb.accesscontrol.windows.net/) 、颁发者名称和颁发者密钥。 使用 Windows PowerShell 检索这些值，如 SB-Messaging 适配器中所述。

  6. 在“ 行为 ”选项卡中，配置此发送端口的终结点行为。

    使用此选项 要执行此操作
    EndpointBehavior 扩展终结点级别发送请求的方式的功能。 可以添加执行不同操作的扩展，例如定义 SOAP 处理行为、指定事务的时间间隔、控制发现功能以及使用其他 .NET 类。

    右键单击“ EndpointBehavior”，然后选择 “添加扩展”。 该列表显示可以使用的 .NET 类。

    这与用于 WCF-Custom 发送端口的终结点行为配置相似。 请参阅 UI 指南和开发人员 API 命名空间参考中的“WCF-自定义传输属性”对话框“发送”和“行为”选项卡。

  7. 在“ 代理 ”选项卡中，配置 WCF-WebHttp 发送端口的代理设置。

    使用此选项 要执行此操作
    使用发送处理程序代理设置 指定此发送端口是否使用承载此发送端口的发送处理程序中的代理设置。

    这是默认设置。
    不使用代理 指示此发送端口是否使用代理服务器。

    默认值为清除此复选框。
    使用代理 指示此发送端口是否使用 Address 属性中指定的代理服务器。

    默认值为清除此复选框。
    Address 指定代理服务器的地址。 根据安全配置使用 https 或 http 方案。 此地址后面可跟冒号和端口号。 例如，http://127.0.0.1:8080。

    仅当选择了 “使用代理” 时，此属性才需要值。

    键入：String

    最大长度：256

    默认值为空字符串。
    用户名 指定用于身份验证的用户名。 如果使用集成身份验证，则用户名将包括域，即采用“域\用户名”格式。 如果使用“基本”或“摘要”验证，则用户名将不包括“域\”。 仅当选择了 “使用代理” 时，此属性才需要值。 注意： WCF-WebHttp 发送适配器对代理使用基本身份验证。

    键入：String

    最小长度：0

    最大长度：256

    默认值为空字符串。
    密码 指定用于身份验证的密码。

    仅当选择了 “使用代理” 时，此属性才需要值。

    键入：String

    最小长度：0

    最大长度：256

    默认值为空字符串。

  8. 在“ 消息 ”选项卡中，指定如何将消息发送到 REST 接口。

    使用此选项 要执行此操作
    出站 HTTP 标头 指定在响应消息中标记的 HTTP 标头（如果有）。
    为谓词取消正文 根据调用 REST 终结点时所用谓词的不同，你可能需要消息负载，也可能不需要。 例如，当使用 GET 或 DELETE 谓词时，你可能不需要消息负载。 但是，若要使用发送端口触发对 REST 终结点的调用，则可能需要使用包含消息负载的虚拟消息。 在将消息发送到 REST 终结点之前，必须从虚拟消息中删除消息负载。 可以使用 Verbs 的取消正文 属性指定必须删除其消息有效负载的谓词。

    例如，如果要在使用 GET 谓词时删除消息有效负载，请将此属性的值指定为 GET。

  9. 再次单击“确定”和“确定”以保存设置。

导入 WCF 扩展

在接收处理程序或发送处理程序中导入 WCF 扩展：

  1. 在“BizTalk Server管理”中，依次展开“BizTalk Server管理”、“BizTalk 组”、“平台设置”和“适配器”。

  2. 选择“ WCF-WebHttp”，然后双击接收或发送处理程序。

  3. 在“常规”选项卡中，选择“ 属性”。

  4. 在 “WCF 扩展”中，选择“ 导入”，并浏览到 WCF 扩展配置文件。

将代理添加到发送处理程序

可以将代理添加到发送端口或发送处理程序。 如果要在发送端口添加代理，请跳过此部分。

  1. 在BizTalk Server管理控制台中，依次展开“BizTalk Server管理”、“BizTalk 组”、“平台设置”和“适配器”。

  2. 选择“ WCF-WebHttp”，然后选择发送处理程序。

  3. 在 “适配器处理程序属性”的“ 常规 ”选项卡上，选择“ 属性”。

  4. 在“ 代理 ”选项卡中，执行以下操作。

    使用此选项 要执行此操作
    使用代理 指示此发送处理程序是否使用代理服务器。

    默认值为清除此复选框。
    Address 指定代理服务器的地址。 根据安全配置使用 https 或 http 方案。 此地址后面可跟冒号和端口号。 例如，http://127.0.0.1:8080。

    仅当选择了 “使用代理” 时，此属性才需要值。

    键入：String

    最大长度：256

    默认值为空字符串。
    用户名 指定用于身份验证的用户名。 如果使用集成或基本验证，则用户名将包括域，即采用“域\用户名”格式。 如果使用摘要身份验证，则用户名将不包括“域\”。

    仅当选择了 “使用代理” 时，此属性才需要值。

    键入：String

    最小长度：0

    最大长度：256

    默认值为空字符串。
    密码 指定用于身份验证的密码。

    仅当选择了 “使用代理” 时，此属性才需要值。

    键入：String

    最小长度：0

    最大长度：256

    默认值为空字符串。

  5. 单击“ 确定” ，直到退出所有对话框。

另请参阅

SB-消息适配器

使用适配器

WCF 适配器概述