HttpClientHttpClient

重要な APIImportant APIs

HTTP 2.0 プロトコルと HTTP 1.1 プロトコルを使って情報を送受信するには、HttpClient とその他の Windows.Web.Http 名前空間 API を使います。Use HttpClient and the rest of the Windows.Web.Http namespace API to send and receive information using the HTTP 2.0 and HTTP 1.1 protocols.

HttpClient と Windows.Web.Http 名前空間の概要Overview of HttpClient and the Windows.Web.Http namespace

Windows.Web.Http 名前空間、関連する Windows.Web.Http.Headers 名前空間、Windows.Web.Http.Filters 名前空間のクラスには、基本的な GET 要求を実行したり、次のようなさらに高度な HTTP 機能を実装したりするための HTTP クライアントとして動作する、ユニバーサル Windows プラットフォーム (UWP) アプリ用のプログラミング インターフェイスが用意されています。The classes in the Windows.Web.Http namespace and the related Windows.Web.Http.Headers and Windows.Web.Http.Filters namespaces provide a programming interface for Universal Windows Platform (UWP) apps that act as an HTTP client to perform basic GET requests or implement more advanced HTTP functionality listed below.

  • 一般的な動詞 (DELETEGETPUTPOST) に対応するメソッド。Methods for common verbs (DELETE, GET, PUT, and POST). これらの各要求は、非同期操作として送られます。Each of these requests are sent as an asynchronous operation.

  • 一般的な認証設定とパターンのサポート。Support for common authentication settings and patterns.

  • トランスポートに関する Secure Sockets Layer (SSL) 詳細へのアクセス。Access to Secure Sockets Layer (SSL) details on the transport.

  • カスタマイズされたフィルターを高度なアプリに含める機能。Ability to include customized filters in advanced apps.

  • Cookie を取得、設定、削除する機能。Ability to get, set, and delete cookies.

  • 非同期メソッドで利用可能な HTTP 要求の進行状況情報。HTTP Request progress info available on asynchronous methods.

Windows.Web.Http.HttpRequestMessage クラスは、Windows.Web.Http.HttpClient から送られた HTTP 要求メッセージを表します。The Windows.Web.Http.HttpRequestMessage class represents an HTTP request message sent by Windows.Web.Http.HttpClient. Windows.Web.Http.HttpResponseMessage クラスは、HTTP 要求から受け取った HTTP 応答メッセージを表します。The Windows.Web.Http.HttpResponseMessage class represents an HTTP response message received from an HTTP request. HTTP メッセージは、IETF によって RFC 2616 で規定されています。HTTP messages are defined in RFC 2616 by the IETF.

Windows.Web.Http 名前空間は、クッキーを含む HTTP エンティティ ボディおよびヘッダーとして HTTP コンテンツを表します。The Windows.Web.Http namespace represents HTTP content as the HTTP entity body and headers including cookies. HTTP コンテンツは、HTTP 要求または HTTP 応答に関連付けることができます。HTTP content can be associated with an HTTP request or an HTTP response. Windows.Web.Http 名前空間には、HTTP コンテンツを表す多数のさまざまなクラスが用意されています。The Windows.Web.Http namespace provides a number of different classes to represent HTTP content.

  • HttpBufferContentHttpBufferContent. バッファーとしてのコンテンツ。Content as a buffer
  • HttpFormUrlEncodedContentHttpFormUrlEncodedContent. application/x-www-form-urlencoded MIME タイプでエンコードされた名前と値の組としてのコンテンツ。Content as name and value tuples encoded with the application/x-www-form-urlencoded MIME type
  • HttpMultipartContentHttpMultipartContent. multipart/* MIME タイプ形式のコンテンツ。Content in the form of the multipart/* MIME type.
  • HttpMultipartFormDataContentHttpMultipartFormDataContent. multipart/form-data MIME タイプとしてエンコードされているコンテンツ。Content that is encoded as the multipart/form-data MIME type.
  • HttpStreamContentHttpStreamContent. ストリームとしてのコンテンツ (この内部タイプは、HTTP GET メソッドでのデータの受信、および HTTP POST メソッドでのデータのアップロードに使われます)。Content as a stream (the internal type is used by the HTTP GET method to receive data and the HTTP POST method to upload data)
  • HttpStringContentHttpStringContent. 文字列としてのコンテンツ。Content as a string.
  • IHttpContent - 開発者が独自のコンテンツ オブジェクトを作成するための基本インターフェイスIHttpContent - A base interface for developers to create their own content objects

「HTTP 経由でシンプルな GET 要求を送信する」セクションのコード スニペットでは、HttpStringContent クラスを使って、HTTP GET 要求からの HTTP 応答を文字列として表しています。The code snippet in the "Send a simple GET request over HTTP" section uses the HttpStringContent class to represent the HTTP response from an HTTP GET request as a string.

Windows.Web.Http.Headers 名前空間では、HTTP ヘッダーと Cookie の作成がサポートされます。これらはプロパティとして、HttpRequestMessage オブジェクトと HttpResponseMessage オブジェクトに関連付けられます。The Windows.Web.Http.Headers namespace supports creation of HTTP headers and cookies, which are then associated as properties with HttpRequestMessage and HttpResponseMessage objects.

HTTP 経由でシンプルな GET 要求を送信するSend a simple GET request over HTTP

この記事の中で既に説明したように、Windows.Web.Http 名前空間は、UWP アプリで GET 要求を送信できるようにします。As mentioned earlier in this article, the Windows.Web.Http namespace allows UWP apps to send GET requests. 次のコード スニペットでは、Windows.Web.Http.HttpClient クラスを使って http://www.contoso.com に GET 要求を送信し、Windows.Web.Http.HttpResponseMessage クラスを使って GET 要求からの応答を読み取る方法を示します。The following code snippet demonstrates how to send a GET request to http://www.contoso.com using the Windows.Web.Http.HttpClient class and the Windows.Web.Http.HttpResponseMessage class to read the response from the GET request.

//Create an HTTP client object
Windows.Web.Http.HttpClient httpClient = new Windows.Web.Http.HttpClient();

//Add a user-agent header to the GET request. 
var headers = httpClient.DefaultRequestHeaders;

//The safe way to add a header value is to use the TryParseAdd method and verify the return value is true,
//especially if the header value is coming from user input.
string header = "ie";
if (!headers.UserAgent.TryParseAdd(header))
{
    throw new Exception("Invalid header value: " + header);
}

header = "Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)";
if (!headers.UserAgent.TryParseAdd(header))
{
    throw new Exception("Invalid header value: " + header);
}

Uri requestUri = new Uri("http://www.contoso.com");

//Send the GET request asynchronously and retrieve the response as a string.
Windows.Web.Http.HttpResponseMessage httpResponse = new Windows.Web.Http.HttpResponseMessage();
string httpResponseBody = "";

try
{
    //Send the GET request
    httpResponse = await httpClient.GetAsync(requestUri);
    httpResponse.EnsureSuccessStatusCode();
    httpResponseBody = await httpResponse.Content.ReadAsStringAsync();
}
catch (Exception ex)
{
    httpResponseBody = "Error: " + ex.HResult.ToString("X") + " Message: " + ex.Message;
}
// pch.h
#pragma once
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Web.Http.Headers.h>

// main.cpp : Defines the entry point for the console application.
#include "pch.h"
#include <iostream>
using namespace winrt;
using namespace Windows::Foundation;

int main()
{
    init_apartment();

    // Create an HttpClient object.
    Windows::Web::Http::HttpClient httpClient;

    // Add a user-agent header to the GET request.
    auto headers{ httpClient.DefaultRequestHeaders() };

    // The safe way to add a header value is to use the TryParseAdd method, and verify the return value is true.
    // This is especially important if the header value is coming from user input.
    std::wstring header{ L"ie" };
    if (!headers.UserAgent().TryParseAdd(header))
    {
        throw L"Invalid header value: " + header;
    }

    header = L"Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)";
    if (!headers.UserAgent().TryParseAdd(header))
    {
        throw L"Invalid header value: " + header;
    }

    Uri requestUri{ L"http://www.contoso.com" };

    // Send the GET request asynchronously, and retrieve the response as a string.
    Windows::Web::Http::HttpResponseMessage httpResponseMessage;
    std::wstring httpResponseBody;

    try
    {
        // Send the GET request.
        httpResponseMessage = httpClient.GetAsync(requestUri).get();
        httpResponseMessage.EnsureSuccessStatusCode();
        httpResponseBody = httpResponseMessage.Content().ReadAsStringAsync().get();
    }
    catch (winrt::hresult_error const& ex)
    {
        httpResponseBody = ex.message();
    }
    std::wcout << httpResponseBody;
}

HTTP 経由でバイナリ データを POST するPOST binary data over HTTP

次の C++/WinRT コードでは、フォーム データと POST 要求を使って、少量のバイナリ データをファイルのアップロードとして Web サーバーに送信する例を示します。The C++/WinRT code example below illustrates using form data and a POST request to send a small amount of binary data as a file upload to a web server. そのコードでは、HttpBufferContent クラスを使ってバイナリ データを表し、HttpMultipartFormDataContent クラスを使ってマルチパートのフォーム データを表しています。The code uses the HttpBufferContent class to represent the binary data, and the HttpMultipartFormDataContent class to represent the multi-part form data.

注意

UI スレッドの場合は、(次のコード例で示されているように) get を呼び出すのは適切ではありません。Calling get (as seen in the code example below) isn't appropriate for a UI thread. その場合に使用する正しい方法については、「Concurrency and asynchronous operations with C++/WinRT」(C++/WinRT を使用した同時実行操作と非同期操作) をご覧ください。For the correct technique to use in that case, see Concurrency and asynchronous operations with C++/WinRT.

// pch.h
#pragma once
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Security.Cryptography.h>
#include <winrt/Windows.Storage.Streams.h>
#include <winrt/Windows.Web.Http.Headers.h>

// main.cpp : Defines the entry point for the console application.
#include "pch.h"
#include <iostream>
#include <sstream>
using namespace winrt;
using namespace Windows::Foundation;
using namespace Windows::Storage::Streams;

int main()
{
    init_apartment();

    auto buffer{
        Windows::Security::Cryptography::CryptographicBuffer::ConvertStringToBinary(
            L"A sentence of text to encode into binary to serve as sample data.",
            Windows::Security::Cryptography::BinaryStringEncoding::Utf8
        )
    };
    Windows::Web::Http::HttpBufferContent binaryContent{ buffer };
    // You can use the 'image/jpeg' content type to represent any binary data;
    // it's not necessarily an image file.
    binaryContent.Headers().Append(L"Content-Type", L"image/jpeg");

    Windows::Web::Http::Headers::HttpContentDispositionHeaderValue disposition{ L"form-data" };
    binaryContent.Headers().ContentDisposition(disposition);
    // The 'name' directive contains the name of the form field representing the data.
    disposition.Name(L"fileForUpload");
    // Here, the 'filename' directive is used to indicate to the server a file name
    // to use to save the uploaded data.
    disposition.FileName(L"file.dat");

    Windows::Web::Http::HttpMultipartFormDataContent postContent;
    postContent.Add(binaryContent); // Add the binary data content as a part of the form data content.

    // Send the POST request asynchronously, and retrieve the response as a string.
    Windows::Web::Http::HttpResponseMessage httpResponseMessage;
    std::wstring httpResponseBody;

    try
    {
        // Send the POST request.
        Uri requestUri{ L"https://www.contoso.com/post" };
        Windows::Web::Http::HttpClient httpClient;
        httpResponseMessage = httpClient.PostAsync(requestUri, postContent).get();
        httpResponseMessage.EnsureSuccessStatusCode();
        httpResponseBody = httpResponseMessage.Content().ReadAsStringAsync().get();
    }
    catch (winrt::hresult_error const& ex)
    {
        httpResponseBody = ex.message();
    }
    std::wcout << httpResponseBody;
}

実際のバイナリ ファイルの内容を POST するには (上で使用した明示的なバイナリ データではなく)、HttpStreamContent オブジェクトを使う方が簡単であることがわかります。To POST the contents of an actual binary file (rather than the explicit binary data used above), you'll find it easier to use an HttpStreamContent object. それを構築し、そのコンストラクターへの引数として、StorageFile.OpenReadAsync の呼び出しから返された値を渡します。Construct one and, as the argument to its constructor, pass the value returned from a call to StorageFile.OpenReadAsync. そのメソッドからは、バイナリ ファイル内のデータに対するストリームが返されます。That method returns a stream for the data inside your binary file.

また、大きいファイル (約 10 MB より大) をアップロードする場合は、Windows ランタイムのバックグラウンド転送 API を使うことをお勧めします。Also, if you're uploading a large file (larger than about 10MB), then we recommend that you use the Windows Runtime Background Transfer APIs.

HTTP 経由で JSON データを POST するPOST JSON data over HTTP

次の例では、エンドポイントに JSON を POST した後、応答本文を書き出しています。The following example posts some JSON to an endpoint, then writes out the response body.

using System;
using System.Diagnostics;
using System.Threading.Tasks;
using Windows.Storage.Streams;
using Windows.Web.Http;

private async Task TryPostJsonAsync()
{
    try
    {
        // Construct the HttpClient and Uri. This endpoint is for test purposes only.
        HttpClient httpClient = new HttpClient();
        Uri uri = new Uri("https://www.contoso.com/post");

        // Construct the JSON to post.
        HttpStringContent content = new HttpStringContent(
            "{ \"firstName\": \"Eliot\" }",
            UnicodeEncoding.Utf8,
            "application/json");

        // Post the JSON and wait for a response.
        HttpResponseMessage httpResponseMessage = await httpClient.PostAsync(
            uri,
            content);

        // Make sure the post succeeded, and write out the response.
        httpResponseMessage.EnsureSuccessStatusCode();
        var httpResponseBody = await httpResponseMessage.Content.ReadAsStringAsync();
        Debug.WriteLine(httpResponseBody);
    }
    catch (Exception ex)
    {
        // Write out any exceptions.
        Debug.WriteLine(ex);
    }
}

Windows.Web.Http の例外Exceptions in Windows.Web.Http

Uniform Resource Identifier (URI) として無効な文字列が、Windows.Foundation.Uri オブジェクトのコンストラクターに渡されると、例外がスローされます。An exception is thrown when an invalid string for a the Uniform Resource Identifier (URI) is passed to the constructor for the Windows.Foundation.Uri object.

.NET:   Windows.Foundation.Uri 型は、C# や VB では System.Uri と表示されます。.NET:  The Windows.Foundation.Uri type appears as System.Uri in C# and VB.

C# や Visual Basic では、.NET 4.5 の System.Uri クラスと、System.Uri.TryCreate メソッドの 1 つを使って、URI が作成される前にユーザーから受け取った文字列をテストすることによって、このエラーを回避できます。In C# and Visual Basic, this error can be avoided by using the System.Uri class in the .NET 4.5 and one of the System.Uri.TryCreate methods to test the string received from a user before the URI is constructed.

C++ では、URI として渡される文字列を試行して解析するメソッドはありません。In C++, there is no method to try and parse a string to a URI. アプリがユーザーから Windows.Foundation.Uri の入力を取得する場合、このコンストラクターを try/catch ブロックに配置する必要があります。If an app gets input from the user for the Windows.Foundation.Uri, the constructor should be in a try/catch block. 例外がスローされた場合、アプリは、ユーザーに通知し、新しいホスト名を要求することができます。If an exception is thrown, the app can notify the user and request a new hostname.

Windows.Web.Http には便利な関数がありません。The Windows.Web.Http lacks a convenience function. そのため、この名前空間の HttpClient と他のクラスを使うアプリは、HRESULT 値を使う必要があります。So an app using HttpClient and other classes in this namespace needs to use the HRESULT value.

C# と VB.NET で .NET Framework 4.5 を使うアプリでは、アプリの実行中に例外が発生した場合、System.Exception でエラーが表されます。In apps using the .NET Framework 4.5 in C#, VB.NET, the System.Exception represents an error during app execution when an exception occurs. System.Exception.HResult プロパティは、特定の例外に割り当てられた HRESULT を返します。The System.Exception.HResult property returns the HRESULT assigned to the specific exception. System.Exception.Message プロパティは、例外を説明するメッセージを返します。The System.Exception.Message property returns the message that describes the exception. 使うことができる HRESULT 値は、Winerror.h ヘッダー ファイルに記載されています。Possible HRESULT values are listed in the Winerror.h header file. アプリは特定の HRESULT 値に対するフィルター処理を行い、例外の原因に応じてアプリの動作を変更できます。An app can filter on specific HRESULT values to modify app behavior depending on the cause of the exception.

Managed C++ を使うアプリでは、アプリの実行中に例外が発生したときに、Platform::Exception がエラーを表します。In apps using managed C++, the Platform::Exception represents an error during app execution when an exception occurs. Platform::Exception::HResult プロパティは、特定の例外に割り当てられた HRESULT を返します。The Platform::Exception::HResult property returns the HRESULT assigned to the specific exception. Platform::Exception::Message プロパティは、HRESULT 値に関連付けられた、システムが提供する文字列を返します。The Platform::Exception::Message property returns the system-provided string that is associated with the HRESULT value. 使うことができる HRESULT 値は、Winerror.h ヘッダー ファイルに記載されています。Possible HRESULT values are listed in the Winerror.h header file. アプリは特定の HRESULT 値に対するフィルター処理を行い、例外の原因に応じてアプリの動作を変更できます。An app can filter on specific HRESULT values to modify app behavior depending on the cause of the exception.

ほとんどのパラメーター検証エラーの場合、返される HRESULTE_INVALIDARG です。For most parameter validation errors, the HRESULT returned is E_INVALIDARG. 一部の無効なメソッド呼び出しでは、返される HRESULTE_ILLEGAL_METHOD_CALL です。For some illegal method calls, the HRESULT returned is E_ILLEGAL_METHOD_CALL.