第一章 发送HTTP请求

本主题介绍如何发送HTTP请求(如POST或GET)和处理响应。

HTTP请求简介

可以创建%Net.HttpRequest的实例来发送各种HTTP请求并接收响应。此对象相当于Web浏览器，可以使用它发出多个请求。它会自动发送正确的cookie，并根据需要设置Referer标头。

要创建HTTP请求，请使用以下常规流程：

1. 创建%Net.HttpRequest的实例。
2. 设置此实例的属性以指示要与之通信的Web服务器。基本属性如下：

• 服务器指定Web服务器的IP地址或计算机名称。默认值为localhost。

注意：不要将http：//或https：//作为服务器值的一部分。这将导致错误#6059：无法打开到服务器http：/的TCP/IP套接字。

3. 可以选择设置HTTP请求的其他属性和调用方法，如指定其他HTTP请求属性中所述。
4. 然后，通过调用%Net.HttpRequest实例的get()方法或其他方法来发送HTTP请求，如“发送HTTP请求”中所述。

可以从实例发出多个请求，它将自动处理cookie和Referer标头。

注意：如果创建此HTTP请求是为了与生产出站适配器(EnsLib.HTTP.Outbound Adapter)一起使用，那么请改用该适配器的方法来发送请求。

5. 如果需要，使用%Net.HttpRequest的同一实例发送其他HTTP请求。默认情况下，InterSystems IRIS使TCP/IP套接字保持打开状态，以便可以重复使用套接字，而无需关闭和重新打开它。

以下是一个简单的示例：

/// w ##class(PHA.TEST.HTTP).Get()
ClassMethod Get()
{
    set request=##class(%Net.HttpRequest).%New()
    set request.Server="tools.ietf.org"
    set request.Https=1
    set request.SSLConfiguration="yx"
    set status=request.Get("/html/rfc7158")
    d $System.Status.DisplayError(status) 

    s response = request.HttpResponse
    s stream = response.Data
    q stream.Read()
}

提供身份验证

如果目标服务器需要登录凭据，则HTTP请求可以包括提供凭据的HTTP Authorization标头。

如果使用的是代理服务器，还可以指定代理服务器的登录凭据；为此，请设置ProxyAuthorization属性

使用HTTP 1.0时对请求进行身份验证

对于HTTP 1.0，要验证HTTP请求，请设置%Net.HttpRequest实例的用户名和密码属性。然后，该实例使用基本访问身份验证基于该用户名和密码创建HTTP Authorization标头(RFC 2617)。此%Net.HttpRequest发送的任何后续请求都将包括此头。

重要提示：请确保还使用SSL。在基本身份验证中，凭据以base-64编码形式发送，因此易于读取。

在使用HTTP 1.1时对请求进行身份验证

对于HTTP 1.1，要验证HTTP请求，在大多数情况下，只需设置%Net.HttpRequest实例的用户名和密码属性。当%Net.HttpRequest的实例收到401 HTTP状态代码和WWW-Authenticate标头时，它会尝试使用包含支持的身份验证方案的Authorization标头进行响应。使用为IRIS支持和配置的第一个方案。默认情况下，它按以下顺序考虑这些身份验证方案：

1. 协商(SPNEGO和Kerberos，根据RFC 4559和RFC 4178)
2. NTLM(NT LAN Manager身份验证协议)
3. 基本认证(RFC 2617中描述的基本接入认证)

重要:如果有可能使用基本身份验证，请确保也使用SSL(参见“使用SSL进行连接”)。
在基本身份验证中，凭据以base-64编码的形式发送，因此很容易读取。

在Windows上，如果没有指定Username属性，IRIS可以使用当前登录上下文。
具体来说，如果服务器使用401状态码和用于SPNEGO、Kerberos或NTLM的WWW-Authenticate头响应，那么IRIS将使用当前操作系统用户名和密码创建Authorization头。

具体情况与HTTP 1.0不同，如下所示:

1. 如果认证成功，IRIS更新%Net的CurrentAuthenticationScheme属性。
   HttpRequest实例来指示它在最近的身份验证中使用的身份验证方案。
2. 如果尝试获取方案的身份验证句柄或令牌失败，IRIS会将基础错误保存到%Net.HttpRequest实例的AuthenticationErrors属性中。此属性的值为$List，其中每一项都具有格式scheme ERROR: message

仅HTTP 1.1支持协商和NTLM，因为这些方案需要多次往返，而HTTP 1.0要求在每个请求/响应对之后关闭连接。

Variations

如果知道服务器允许的一个或多个身份验证方案，则可以通过包括Authorization标头来绕过服务器的初始往返行程，该标头包含所选方案的服务器的初始令牌。为此，请设置%Net.HttpRequest实例的InitiateAuthentication属性。对于此属性的值，请指定服务器允许的单个授权方案的名称。使用下列值之一(区分大小写)：
- Negotiate
- NTLM
- Basic

如果要自定义要使用的身份验证方案(或更改其考虑顺序)，请设置%Net.HttpRequest实例的AuthenticationSchemes。对于此属性的值，请指定以逗号分隔的身份验证方案名称列表(使用上一个列表中给出的准确值)。

直接指定授权标头

对于HTTP 1.0或HTTP 1.1(如果适用于场景)，可以直接指定HTTP Authorization标头。具体地说，可以将Authorization属性设置为等于正在请求的资源的用户代理所需的身份验证信息。

如果指定Authorization属性，则忽略用户名和密码属性。

启用HTTP身份验证的日志记录

要启用HTTP身份验证的日志记录，请在终端中输入以下内容：

 set $namespace="%SYS"
 kill ^ISCLOG
 set ^%ISCLOG=2
 set ^%ISCLOG("Category","HttpRequest")=5

日志条目将写入^ISCLOG global中.。要将日志写入文件(以提高可读性)，请输入以下内容(仍在%SYS命名空间内)：

 do ##class(%OAuth2.Utils).DisplayLog("filename")

其中，filename是要创建的文件的名称。该目录必须已存在。如果该文件已经存在，它将被覆盖。

要停止日志记录，请输入以下内容(仍在%SYS命名空间内)：

 set ^%ISCLOG=0
 set ^%ISCLOG("Category","HttpRequest")=0

指定其他HTTP请求属性

在发送HTTP请求之前(请参阅发送HTTP请求)，可以指定其属性，如以下各节所述：

可以为%Net.HttpRequest的所有属性指定默认值，如最后列出的部分中所指定。

Location属性

Location属性指定从Web服务器请求的资源。如果设置此属性，则在调用Get(), Head(), Post(), 或 Put()方法时，可以省略location参数。

例如，假设正在向url http://machine_name/test/index.html发送一个HTTP请求

在这种情况下，将使用下列值：

%Net.HttpRequest的示例属性

指定Internet媒体类型（Media Type）和字符编码（Character Encoding）

可以使用以下属性指定%Net.HttpRequest实例及其响应中的Internet媒体类型(也称为MIME类型)和字符编码：

• Content-Type指定Content-Type标头，该标头指定请求正文的Internet媒体类型。默认类型为None。

可能的值包括application/json、application/pdf、application/postscript、image/jpeg、image/png、multipart/form-data、text/html、text/plan、text/xml等等

• ContentCharset属性控制请求的任何内容(例如，text/html或text/xml)类型时所需的字符集。如果不指定此属性，InterSystems IRIS将使用InterSystems IRIS服务器的默认编码。

注意：如果设置此属性，则必须首先设置ContentType属性。

• NoDefaultContentCharset属性控制在未设置ContentCharset属性的情况下是否包括文本类型内容的显式字符集。默认情况下，此属性为False。

如果此属性为true，则如果有文本类型的内容，并且没有设置ContentCharset属性，则内容类型中不包括任何字符集；这意味着字符集iso-8859-1用于消息输出。

• WriteRawMode属性影响实体正文(如果包含)。它控制请求正文的写入方式。默认情况下，此属性为False，并且InterSystems IRIS以请求标头中指定的编码写入正文。如果此属性为true，则InterSystems IRIS以原始模式写入正文(不执行字符集转换)。
• ReadRawMode属性控制如何读取响应正文。默认情况下，此属性为False，并且InterSystems IRIS假定正文在响应标头中指定的字符集中。如果此属性为true，InterSystems IRIS将以原始模式读取正文(不执行字符集转换)。

使用代理服务器

可以通过代理服务器发送HTTP请求。要设置此设置，请指定HTTP请求的以下属性：
- ProxyServer指定要使用的代理服务器的主机名。如果此属性不为空，则将HTTP请求定向到此计算机。
- ProxyPort指定代理服务器上要连接到的端口。
- ProxyAuthorization指定Proxy-Authorization标头，如果用户代理必须使用代理验证其自身，则必须设置该标头。对于该值，请使用正在请求的资源的用户代理所需的身份验证信息。
- ProxyHTTPS控制HTTP请求是针对HTTPS页面还是针对普通HTTP页面。如果未指定代理服务器，则忽略此属性。此属性将目标系统上的默认端口更改为代理端口443。
- ProxyTunes指定是否通过代理建立到目标HTTP服务器的隧道。如果为true，则请求使用HTTP CONNECT命令建立隧道。代理服务器的地址取自ProxyServer和ProxyPort属性。如果ProxyHttps为true，则隧道建立后，系统间IRIS将协商SSL连接。在这种情况下，由于隧道与目标系统建立直接连接，因此将忽略https属性。

使用SSL进行连接

%Net.HttpRequest类支持SSL连接。要通过SSL发送请求，请执行以下操作：

1. 将SSLConfiguration属性设置为要使用的已激活SSL/TLS配置的名称。

2. 还要执行以下操作之一，具体取决于是否使用代理服务器：

• 如果未使用代理服务器，请将https属性设置为true。
• 如果使用的是代理服务器，请将ProxyHTTPS属性设置为true。

在这种情况下，要使用到代理服务器本身的SSL连接，请将https属性设置为true。

请注意，当使用到给定服务器的SSL连接时，该服务器上的默认端口假定为443(HTTPS端口)。例如，如果没有使用代理服务器，并且https为true，则会将Default Port属性更改为443。

服务器身份检查

默认情况下，当%Net.HttpRequest实例连接到SSL/TLS安全的Web服务器时，它会检查证书服务器名称是否与用于连接到服务器的DNS名称匹配。如果这些名称不匹配，则不允许连接。此默认行为可防止“中间人”攻击，在RFC 2818的3.1节中进行了描述；另请参阅RFC 2595的2.4节。

若要禁用此检查，请将SSLCheckServerIdentity属性设置为0。

HTTPVersion、Timeout、WriteTimeout和FollowRedirect属性

%Net.HttpRequest还提供以下属性：

HTTPVersion指定请求页面时使用的HTTP版本。默认值是"HTTP/1.1"。你也可以使用“HTTP/1.0”。

Timeout指定等待web服务器响应的时间，以秒为单位。
缺省值是30秒。

WriteTimeout指定等待Web服务器完成写入的时间(以秒为单位)。默认情况下，它将无限期等待。可接受的最小值为2秒。

FollowRedirect指定是否自动跟踪来自Web服务器的重定向请求(由300-399范围内的HTTP状态代码发出信号)。如果使用的是GET或HEAD，则默认值为TRUE；否则为FALSE。

指定HTTP请求的默认值

可以为%Net.HttpRequest的所有属性指定默认值。
- 要指定适用于所有名称空间的默认值，请设置全局节 ^%SYS("HttpRequest","propname")，其中“PropName”是属性的名称。
- 要为一个名称空间指定默认值，请转到该名称空间并设置节点^SYS("HttpRequest","propname")

(^%SYS全局设置会影响整个安装，^SYS全局设置会影响当前命名空间。)

例如，要为所有名称空间指定默认代理服务器，请设置全局节^%SYS("HttpRequest","ProxyServer")