HTTP 要求の送信

HTTP 1.0 を使用する場合の要求の認証

HTTP 1.0 の場合に HTTP 要求を認証するには、%Net.HttpRequestOpens in a new tab.のインスタンスの Username プロパティと Password プロパティを設定します。このインスタンスでは次に、Basic アクセス認証 (RFC 2617Opens in a new tab) を使用して、そのユーザ名とパスワードに基づいて HTTP Authorization ヘッダが作成されます。この %Net.HttpRequestOpens in a new tab から送信される以降の要求に、このヘッダが含まれるようになります。

HTTP 1.1 を使用する場合の要求の認証

HTTP 1.1 の場合に HTTP 要求を認証するには、ほとんどの場合、%Net.HttpRequestOpens in a new tab.のインスタンスの Username プロパティと Password プロパティを設定するだけです。%Net.HttpRequestOpens in a new tab のインスタンスが 401 HTTP ステータス・コードと WWW-Authenticate ヘッダを受け取ると、このインスタンスは、サポートされている認証スキームが含まれる Authorization ヘッダを使用して応答しようとします。サポートされており InterSystems IRIS 向けに構成されている最初のスキームが使用されます。既定では、以下の認証スキームがこの順序で検討されます。

1. Negotiate (RFC 4559Opens in a new tab および RFC 4178Opens in a new tab で説明されている SPNEGO および Kerberos)

2. NTLM (NT LAN Manager 認証プロトコル)

3. Basic (RFC 2617Opens in a new tab で説明されている Basic アクセス認証)

   Important:

   Basic 認証が使用される可能性がある場合、SSL も使用していることを確認してください ("“SSL を使用した接続” を参照)。Basic 認証では、資格情報は Base 64 のエンコード形式で送信されるため、簡単に読み取ることができます。

Windows では、Username プロパティが指定されていない場合、InterSystems IRIS は代わりに現在のログイン・コンテキストを使用できます。具体的には、SPNEGO、Kerberos、または NTLM の場合にサーバが 401 ステータス・コードと WWW-Authenticate ヘッダを使用して応答すると、InterSystems IRIS は現在のオペレーティング・システムのユーザ名とパスワードを使用して、Authorization ヘッダを作成します。

以下に示すように、HTTP 1.0 の場合とは詳細が異なります。

• 認証が成功すると、最新の認証に使用された認証スキームを示すように、InterSystems IRIS は %Net.HttpRequestOpens in a new tab インスタンスの CurrentAuthenticationScheme プロパティを更新します。

• スキームの認証ハンドルまたはトークンを取得しようとして失敗した場合、InterSystems IRIS は原因となっているエラーを %Net.HttpRequestOpens in a new tab インスタンスの AuthenticationErrors プロパティに保存します。このプロパティの値は $LIST で、各項目が scheme ERROR: message の形式になっています。

Negotiate と NTLM は HTTP 1.1 でのみサポートされています。これらのスキームには複数回の往復が必要ですが、HTTP 1.0 では要求と応答の各ペアの後に接続を閉じる必要があるからです。

Authorization ヘッダを直接指定する方法

HTTP 1.0 と HTTP 1.1 (シナリオに適用できる場合) のいずれの場合でも、HTTP Authorization ヘッダを直接指定できます。具体的には、要求しているリソースのユーザ・エージェントに必要な認証情報に等しい値に Authorization プロパティを設定します。

Authorization プロパティを指定すると、Username プロパティと Password プロパティは無視されます。

HTTP 認証のログの有効化

HTTP 認証のログを有効にするには、ターミナルで以下を入力します。

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

ログ・エントリは、^ISCLOG グローバルに書き込まれます。ログをファイルに書き込むには (読みやすくするため)、以下を入力します (引き続き、%SYS ネームスペース内です)。

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

filename は、作成するファイルの名前です。このディレクトリは既に存在している必要があります。ファイルが既に存在する場合は、そのファイルが上書きされます。

ログを停止するには、以下を入力します (引き続き、%SYS ネームスペース内です)。

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

Location プロパティ

Location プロパティでは、Web サーバから要求するリソースを指定します。このプロパティを設定すると、Get()、Head()、Post()、または Put() の各メソッドを呼び出す際、場所の引数を省略できます。

例えば、URL http://machine_name/test/index.html に HTTP 要求を送信しているとします。

この場合、以下の値を使用します。

インターネット・メディア・タイプと文字エンコードの指定

以下のプロパティを使用して、インターネット・メディア・タイプOpens in a new tab (MIME タイプ とも呼ばれます)、および %Net.HttpRequestOpens in a new tab のインスタンスとそのレスポンス内の文字エンコードを指定できます。

• ContentType では、Content-Type ヘッダを指定します。このヘッダで、要求の本文のインターネット・メディア・タイプを指定します。既定タイプは、None です。

  指定可能な値は、application/json、application/pdf、application/postscript、image/jpeg、image/png、multipart/form-data、text/html、text/plain、text/xml などの他にも多数あります。詳細なリストは、http://www.iana.org/assignments/media-typesOpens in a new tab を参照してください。

• ContentCharset プロパティは、コンテンツがテキスト・タイプ (text/html や text/xml など) の場合、要求のコンテンツのための目的の文字セットを制御します。このプロパティを指定しない場合、InterSystems IRIS では、InterSystems IRIS サーバ既定のエンコーディングが使用されます。

  Note:

  このプロパティを設定する場合、まず、ContentType プロパティを設定する必要があります。

• NoDefaultContentCharset プロパティは、ContentCharset プロパティを設定していない場合、text タイプのコンテンツの明示的な文字セットを含めるかどうかを制御します。既定では、このプロパティは、False です。

  このプロパティが True の場合、text タイプのコンテンツがあり、ContentCharset プロパティが設定されていなければ、コンテンツ・タイプに文字セットは含まれません。つまり、iso-8859-1 文字セットがメッセージの出力に使用されます。

• WriteRawMode プロパティは、エンティティ本文に影響を与えます (含まれる場合)。これは要求の本文の記述方法を制御します。既定では、このプロパティは False であり、要求ヘッダで指定されたエンコーディングで本文に記述されます。このプロパティが True の場合、本文が RAW モードで記述されます (文字セットの変換は行いません)。

• ReadRawMode プロパティは、応答の本文の読み取り方法を制御します。既定では、このプロパティは False であり、本文が応答ヘッダで指定された文字セットであると見なされます。このプロパティが True の場合、本文が RAW モードで読み取られます (文字セットの変換は行いません)。

プロキシ・サーバの使用法

プロキシ・サーバにより、HTTP 要求を送信できます。これを設定するには、HTTP 要求の以下のプロパティを指定します。

• ProxyServer では、使用するプロキシ・サーバのホスト名を指定します。このプロパティが NULL でない場合、HTTP 要求はこのマシンに向けられます。

• ProxyPort では、プロキシ・サーバ上の接続するポートを指定します。

• ProxyAuthorization では、Proxy-Authorization ヘッダを指定します。ユーザ・エージェントがそれ自体をプロキシで認証する必要がある場合に設定する必要があります。値には、要求しているリソースのユーザ・エージェントが必要とする認証情報を使用します。“ログイン資格情報の提供” も参照してください。

• ProxyHTTPS は、HTTP 要求が通常の HTTP ページではなく、HTTPS ページに対するものであるかどうかを制御します。このプロパティは、プロキシ・サーバを指定していない場合、無視されます。このプロパティでは、ターゲット・システムの既定ポートをプロキシ・ポートである 443 に変更します。“SSL を使用した接続” も参照してください。

• ProxyTunnel では、プロキシ経由でターゲットの HTTP サーバへのトンネルを確立するかどうかを指定します。True の場合、要求は HTTP CONNECT コマンドを使用してトンネルを確立します。プロキシ・サーバのアドレスは、ProxyServer プロパティと ProxyPort プロパティから取得されます。ProxyHttps が True の場合、トンネルが確立されたときに InterSystems IRIS が SSL 接続をネゴシエートします。この場合、トンネルによってターゲット・システムとの直接接続が確立されるため、Https プロパティは無視されます。

詳細は、%Net.HttpRequestOpens in a new tab のクラス・ドキュメントを参照してください。

SSL を使用した接続

%Net.HttpRequestOpens in a new tab クラスは、SSL 接続をサポートします。SSL によって要求を送信する手順は以下のとおりです。

1. SSLConfiguration プロパティを使用する有効化した SSL/TLS 構成の名前に設定します。

   SSL/TLS 構成の作成と管理の詳細は、"InterSystems TCP ガイド" を参照してください。SSL/TLS 構成には、[構成名] と呼ばれるオプションが含まれています。これは、この設定で使用する文字列です。

2. プロキシ・サーバを使用しているかどうかによって、以下のいずれかを行います。

   • プロキシ・サーバを使用していない場合、Https プロパティを True に設定します。

   • プロキシ・サーバを使用している場合、ProxyHTTPS プロパティを True に設定します。

     この場合、プロキシ・サーバ自体への SSL 接続を使用するため、Https プロパティを True に設定します。

指定のサーバへの SSL 接続を使用する場合、そのサーバでの既定ポートは 443 (HTTPS ポート) と見なされます。例えば、プロキシ・サーバを使用しておらず、Https が True の場合、これによって、既定の Port プロパティが 443 に変更されます。

“プロキシ・サーバの使用法” も参照してください。

HTTPVersion、Timeout、WriteTimeout、および FollowRedirect プロパティ

%Net.HttpRequestOpens in a new tab には、以下のプロパティもあります。

• HTTPVersion は、ページを要求するときに使用する HTTP のバージョンを指定します。既定値は "HTTP/1.1" です。また、"HTTP/1.0" も使用できます。

• Timeout では、Web サーバからの応答を待機する時間を秒単位で指定します。既定値は 30 秒です。

• WriteTimeout では、Web サーバの書き込み完了を待機する時間を秒単位で指定します。既定では無限に待機します。指定できる最小値は 2 秒です。

• FollowRedirect では、(300 ～ 399 の範囲の HTTP 状態コードによって示される) Web サーバからのリダイレクト要求に自動的に従うかどうかを指定します。既定値は、GET または HEAD を使用している場合は True、それ以外の場合は False です。

HTTP 要求の既定値の指定

%Net.HttpRequestOpens in a new tab のすべてのプロパティの既定値を指定できます。

• すべてのネームスペースに適用する既定値を指定するには、グローバル・ノード ^%SYS("HttpRequest","propname") を設定します。"propname" は、プロパティの名前です。

• 1 つのネームスペースに適用する既定値を指定するには、そのネームスペースに移動し、ノード ^SYS("HttpRequest","propname") を設定します。

  (^%SYS グローバルはインストール全体に、^SYS グローバルは現在のネームスペースに影響を及ぼします。)

例えば、すべてのネームスペースに既定のプロキシ・サーバを指定するには、グローバル・ノード ^%SYS("HttpRequest","ProxyServer") を設定します。

チャンクされた要求の送信

HTTP 1.1 を使用すると、HTTP要求をチャンクで送信できます。これには、Transfer-Encoding を設定してメッセージがチャンクされていることを示し、0 サイズのチャンクを使用して完了を示す必要があります。

チャンク・エンコードは、サーバが大量のデータを返しており、要求が完全に処理されるまで応答の合計サイズが分からない場合に便利です。そのような場合、通常、コンテンツの長さが計算できるまで (これは、%Net.HttpRequestOpens in a new tab が自動的に行います)、メッセージ全体をバッファする必要があります。

チャンクされた要求を送信する手順は以下のとおりです。

1. データをチャンクで書き込むためのインタフェースを定義する抽象ストリーム・クラスである、%Net.ChunkedWriterOpens in a new tab のサブクラスを作成します。

   このサブクラス内に、OutputStream() メソッドを実装します。

2. %Net.HttpRequestOpens in a new tab のインスタンスで、%Net.ChunkedWriterOpens in a new tab サブクラスのインスタンスを作成し、送信する要求データを入力します。

3. %Net.HttpRequestOpens in a new tab インスタンスの EntityBody プロパティを %Net.ChunkedWriterOpens in a new tab のこのインスタンスと等しくなるように設定します。

   HTTP 要求を送信すると (“HTTP 要求の送信” を参照)、EntityBody プロパティの OutputStream() メソッドが呼び出されます。

%Net.ChunkedWriterOpens in a new tab のサブクラスで、OutputStream() メソッドはストリーム・データを調べ、これをチャンクするかどうかとその方法を決定し、クラスの継承されたメソッドを呼び出して出力を記述します。

以下のメソッドを使用できます。

NULL でない場合、TranslateTable プロパティは、記述する際に各文字列の変換に使用する変換テーブルを指定します。前述のメソッドはすべてこのプロパティを確認します。

例 1

フォーム・データを挿入後、通常、Post() メソッドを呼び出します。以下はその例です。

    Do httprequest.InsertFormData("element","value")
    Do httprequest.Post("/cgi-bin/script.CGI")

例 2

別の例を示します。

    Set httprequest=##class(%Net.HttpRequest).%New()
    set httprequest.SSLConfiguration="MySSLConfiguration"
    set httprequest.Https=1
    set httprequest.Server="myserver.com"
    set httprequest.Port=443
    Do httprequest.InsertFormData("portalid","2000000")
    set tSc = httprequest.Post("/url-path/")
    Quit httprequest.HttpResponse

応答のデータへのアクセス

HTTP 応答の本文は、応答の Data プロパティに含まれています。このプロパティには、ストリーム・オブジェクト (具体的には %GlobalBinaryStreamOpens in a new tab) が含まれています。このストリームを使用するには、標準ストリーム・メソッドである Write()、WriteLine()、Read()、ReadLine()、Rewind()、MoveToEnd()、および Clear() を使用します。また、ストリームの Size プロパティも使用できます。

要求 の ReadRawMode プロパティは、応答の本文を読み取る方法を制御します。

• 既定では、このプロパティは False であり、InterSystems IRIS では、本文が、応答の HTTP ヘッダで指定された文字セットである (かつ、それに応じて文字セットを変換している) と見なされます。

• このプロパティが True の場合、本文が RAW モードで読み取られます (文字セットの変換は行いません)。

また、OutputToDevice() メソッドを使用して、完全な応答を現在のデバイスに書き込むこともできます。ヘッダは、Web サーバによって生成された順序と同じ順序ではありません。

以下の簡単な例では、応答ストリームをファイルにコピーして保存します。

 set request=##class(%Net.HttpRequest).%New()
 set request.Server="tools.ietf.org"
 set request.Https=1
 set request.SSLConfiguration="TEST"
 set status=request.Get("/html/rfc7158")
 if $$$ISERR(status) {
         do $system.OBJ.DisplayError()
 } else {
         set response=request.HttpResponse
 }
 
 Set file=##class(%FileCharacterStream).%New()
 set file.Filename="c:/temp/rfc7158.html"
 set status=file.CopyFrom(response.Data)
 if $$$ISERR(status) {
         do $system.OBJ.DisplayError()
 }
 do file.%Close()

名前による HTTP ヘッダの取得

%Net.HttpResponseOpens in a new tab クラスは、InterSystems IRIS 多次元配列内にその HTTP ヘッダを保存します。ヘッダにアクセスするには、以下のメソッドを使用します。

これらの各メソッドは、HTTP ヘッダの名前の文字列である単一の引数を取ります。

また、OutputHeaders() メソッドを使用して、HTTP ヘッダを現在のデバイスに書き込むこともできます (ただし、生成された順番と同じ順番ではありません)。

応答に関するその他の情報へのアクセス

%Net.HttpResponseOpens in a new tab クラスは、HTTP 応答のその他の特定の部分を保存するプロパティを提供します。

• StatusLine は、応答の第 1 行目の HTTP ステータス行を保存します。

• StatusCode は、HTTP ステータス・コードを保存します。

• ReasonPhrase は、StatusCode に相当する人間が読める形式の理由を保存します。

• ContentInfo は、応答本文についての追加情報を保存します。

• ContentType は、Content-Type: ヘッダの値を保存します。

• HttpVersion は、応答を送信した Web サーバがサポートする HTTP のバージョンを示します。