jQuery.ajax() メソッドによる非同期通信の完全ガイド

jQuery.ajax()メソッドは、ウェブページのリロードを行うことなく、バックグラウンドでHTTPリクエストを送信し、リモートサーバーとの間でデータを送受信するためのjQueryの核心的な機能を提供します。これは、現代の動的なウェブアプリケーション構築において不可欠な非同期通信（Ajax）の基盤となります。

このメソッドは、`jQuery.get()`、`jQuery.post()`、`load()`、`jQuery.getJSON()`、`jQuery.getScript()`といった、より高レベルで特定の用途に特化した多くのjQuery Ajax関数が内部的に利用している、低レベルのAPIです。これらの簡易メソッドは、jQuery.ajax()のパラメータの一部を省略またはデフォルト値で設定することで、利用を簡素化しています。jQuery.ajax()自体は、グローバルなjQueryオブジェクトに属する静的メソッドとして提供されます。

構文

jQuery.ajax()メソッドの基本的な呼び出し方には以下の二つの形式があります。

jQuery.ajax( [ settings ] )

jQuery.ajax( url [, settings ] ) // jQuery 1.5以降で追加された形式

パラメータ

settingsオブジェクトには、HTTPリクエストの詳細な設定を行うための様々なプロパティ（オプション）を含めることができます。これらのプロパティはすべて任意です。

主要なオプション

url (String): リクエストの送信先となるURL文字列。settingsオブジェクトのプロパティとしても、またメソッドの最初の引数としても指定できます。
settings (Object): HTTPリクエストの追加設定を指定するプロパティ群を含むオブジェクト。

詳細な設定オプション

accepts (Object)

デフォルトはdataTypeプロパティに依存します。サーバーにレスポンスとして受け入れ可能なコンテンツタイプを伝えるAcceptヘッダーを設定するためのオブジェクト。

async (Boolean)

デフォルトはtrue。非同期リクエストかどうかを指定します。falseに設定すると同期リクエストとなり、サーバーからの応答があるまでブラウザがブロックされ、他の操作ができなくなります。通常はtrueを推奨します。

beforeSend (Function)

リクエストが送信される直前に実行されるコールバック関数です。引数としてjqXHRオブジェクトと現在のsettingsオブジェクトを受け取ります。この関数がfalseを返すと、Ajaxリクエストはキャンセルされます。これはグローバルなAjaxイベントの一つです。

cache (Boolean)

デフォルトはtrue（ただし、dataTypeが'script'または'jsonp'の場合はfalse）。ブラウザがURLリクエストをキャッシュするかどうかを制御します。falseに設定すると、ブラウザが現在のURLリクエストをキャッシュしないように強制します。この設定はHEADおよびGETリクエストにのみ有効です。

complete (Function/Array)

リクエストが成功または失敗にかかわらず「完了」した後に実行されるコールバック関数です。引数としてjqXHRオブジェクトとリクエストの状態を示す文字列（'success', 'notmodified', 'error', 'timeout', 'abort', 'parsererror'のいずれか）を受け取ります。これはグローバルなAjaxイベントの一つです。
jQuery 1.5以降では、複数の関数を配列形式で指定できます。

contents (Object) 1.5 新規

コンテンツタイプをキー、正規表現を値とするオブジェクトです。これにより、jQueryがレスポンスをどのようにパースするかを決定します。

contentType (String)

デフォルトは'application/x-www-form-urlencoded; charset=UTF-8'。サーバーにデータを送信する際の内容エンコーディングタイプを指定します。

context (Object)

Ajax関連のコールバック関数内でthisキーワードが参照するオブジェクトを設定します。

converters (Object) 1.5 新規

デフォルトは{'* text': window.String, 'text html': true, 'text json': jQuery.parseJSON, 'text xml': jQuery.parseXML}。データ型変換器のオブジェクトです。各コンバーターの値は、レスポンスの変換された値を返す関数です。

crossDomain (Boolean) 1.5 新規

デフォルトは、同ドメインリクエストではfalse、クロスドメインリクエストではtrue。明示的にクロスドメインリクエストを強制したい場合（例：JSONP形式の場合）にtrueに設定します。

data (Any)

サーバーに送信するデータです。自動的に文字列に変換されます。GETリクエストの場合、URLの末尾にクエリ文字列として追加されます。

dataFilter (Function)

レスポンスの生データを処理するためのコールバック関数です。引数として、レスポンスの生データ文字列とdataTypeプロパティ文字列を受け取ります。

dataType (String)

デフォルトはjQueryが推測（xml、json、script、htmlのいずれか）。サーバーから返されると期待されるデータのタイプを指定します。以下の値が指定可能です。

'xml' : XMLドキュメントとして処理され、jQueryで操作できます。
'html' : HTML文字列として返されます。
'script' : JavaScriptコードとしてロードされ実行されます。キャッシュは自動的には行われません（cacheパラメータの設定によります）。リモートリクエストの場合、POSTリクエストはGETリクエストに変換されます。
'json' : JSONデータとして返されます。厳密な構文で解析され、解析に失敗するとエラーがスローされます。jQuery 1.9以降、空のレスポンスはnullまたは{}を返します。
'jsonp' : JSONP形式。URL中のcallback=?の部分が、jQueryが生成する正しい関数名に自動的に置換され、コールバック関数が実行されます。
'text' : プレーンテキスト文字列として返されます。

error (Function/Array)

リクエストが「失敗」した場合に実行されるコールバック関数です。引数として、jqXHRオブジェクト、リクエスト状態文字列（null、'timeout'、'error'、'abort'、'parsererror'のいずれか）、エラーメッセージ文字列（HTTPステータスのテキスト説明、例：'Not Found'）を受け取ります。これはグローバルなAjaxイベントの一つです。クロスドメインのスクリプトやJSONPリクエストでは呼び出されない場合があります。
jQuery 1.5以降では、複数の関数を配列形式で指定できます。

global (Boolean)

デフォルトはtrue。グローバルなAjaxイベント（例：ajaxStart()、ajaxStop()）を発火させるかどうかを指定します。falseに設定すると、これらのグローバルイベントのトリガーを抑制します。

headers (Object) 1.5 新規

デフォルトは{}。追加のHTTPリクエストヘッダーをオブジェクト形式で指定します。X-Requested-With: XMLHttpRequestヘッダーは常に自動的に追加されますが、ここで上書きすることも可能です。beforeSendコールバック内で設定されたヘッダー値よりも、headersで指定された値が優先されます。

例:

$.ajax({
    url: "/api/secure-data",
    headers: {
        "X-Custom-Auth": "my_secret_token",
        "Accept-Language": "ja-JP"
    }
});

ifModified (Boolean)

デフォルトはfalse。サーバー側のデータに変更があった場合にのみ新しいデータを取得することを許可します（変更がない場合はブラウザのキャッシュからデータを使用）。これはHTTPヘッダーのLast-Modifiedを利用します。jQuery 1.4以降では、サーバーが指定するetagも変更の判断に使用されます。

isLocal (Boolean) 1.5.1 新規

デフォルトは現在のプロトコルによって異なります。jQueryが通常「ローカル」と認識しない環境（例：ファイルシステム）を、明示的にローカルとして扱うことを許可します。現在、file、*-extension、widgetプロトコルがローカルと認識されます。

jsonp (String)

JSONPリクエストのコールバック関数名を上書きします。URL中のcallback=?のcallback部分をこの値で置き換えます。

jsonpCallback (String/Function)

JSONPリクエストのために特定のリクエストコールバック関数名を指定します。この値はjQueryが自動生成するランダムな関数名の代わりに使用されます。
jQuery 1.5以降では、必要な関数名を返す関数を指定することもできます。

mimeType (String) 1.5.1 新規

XHRのMIMEタイプを上書きするためのMIMEタイプ文字列。

password (String)

HTTPアクセス認証リクエストに応答するためのパスワード。

processData (Boolean)

デフォルトはtrue。dataプロパティ経由で渡されたデータがオブジェクトの場合、デフォルトのコンテンツタイプ"application/x-www-form-urlencoded"に合わせて、クエリ文字列形式に自動的に変換されます。DOMツリー情報や、変換を希望しないその他の情報を送信する場合はfalseに設定します。

scriptCharset (String)

リクエストによってロードされるスクリプトファイルの文字セットを設定します。dataTypeが"jsonp"または"script"で、typeが"GET"の場合にのみ、charsetを強制的に変更するために使用されます。通常、現在のページとリモートデータの文字エンコーディングが異なる場合にのみ使用します。

statusCode (Object) 1.5 新規

デフォルトは{}。HTTPステータスコードと、そのコードが返されたときに呼び出される関数をペアにしたオブジェクトです。例：

$.ajax({
    url: "/api/nonexistent-resource",
    statusCode: {
        404: function() {
            alert("要求されたリソースは見つかりませんでした。");
        },
        200: function() {
            console.log("リクエストは成功しました。");
        }
    }
});

success (Function/Array)

リクエストが「成功」した場合に実行されるコールバック関数です。引数として、サーバーからの応答データ、応答ステータス文字列、jqXHRオブジェクトを受け取ります。これはグローバルなAjaxイベントの一つです。
jQuery 1.5以降では、複数の関数を配列形式で指定できます。

timeout (Number)

リクエストのタイムアウト時間をミリ秒単位で設定します。

traditional (Boolean)

パラメータを伝統的な方法でシリアライズしたい場合にtrueに設定します。

type (String)

デフォルトは"GET"。HTTPリクエストのタイプ（メソッド）を指定します。一般的には'POST'または'GET'を使用しますが、'PUT'、'DELETE'なども指定可能です（ただし、すべてのブラウザでサポートされているわけではありません）。

username (String)

HTTPアクセス認証リクエストに応答するためのユーザー名。

xhr (Function)

デフォルトは、IEではActiveXObject（利用可能な場合）、その他のブラウザではXMLHttpRequest。XMLHttpRequestオブジェクトを生成して返すコールバック関数です。独自のXHR実装を提供したり、機能を拡張したりするためにこのプロパティを上書きできます。

xhrFields (Object) 1.5.1 新規

ネイティブのXHRオブジェクトに対して複数のフィールド名と値を設定するためのオブジェクトです。例えば、クロスドメインリクエストでXHRオブジェクトのwithCredentialsプロパティをtrueに設定したい場合などに利用できます。

$.ajax({
    url: "https://api.example.com/cors-enabled-resource",
    xhrFields: {
        withCredentials: true // クロスドメインリクエストで認証情報（クッキーなど）を送信
    }
});

補足事項

全てのAjaxリクエストで共通のsettingsパラメータを設定する必要がある場合、jQuery.ajaxSetup()関数を使用してグローバルな設定を行うことができます。これにより、各jQuery.ajax()呼び出しで個別に設定する手間を省けます。
jQuery 1.4以前のバージョンでは、complete、success、errorなどのAjaxイベントコールバック関数の第3引数は、jQueryによってラップされたjqXHRオブジェクトではなく、ネイティブのXMLHttpRequestオブジェクトでした。

戻り値

jQuery.ajax()メソッドは、jqXHRオブジェクトを返します。このオブジェクトは、ネイティブのXMLHttpRequestオブジェクトをjQueryでラップしたものであり、[Promise](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise)インターフェースの一部を実装しています。これにより、done()、fail()、always()などのメソッドをチェーンして、リクエストの成功、失敗、完了時の処理を記述できます。（jQuery 1.4以前では、生のXMLHttpRequestオブジェクトが返されました。）

使用例

jQuery.ajax()にパラメータを指定しない場合、デフォルトでは現在のページに対してリクエストを送信し、返されたデータに対する特別な処理は行いません。settingsオブジェクトでよく使用されるプロパティは、url、type、async、data、dataType、success、error、complete、beforeSend、timeoutなどです。

以下のHTML要素を想定します。

<div id="output-area">ここにサーバーからの応答が表示されます。</div>

以下に、jQuery.ajax()メソッドの具体的な使用例を示します。

例1: 基本的なPOSTリクエストと成功時の処理

// サーバーの /api/create-user エンドポイントにユーザー情報をPOST送信します
$.ajax({
    url: "/api/create-user",
    type: "POST", // HTTPメソッドをPOSTに指定
    data: { // 送信するデータはオブジェクト形式で指定
        firstName: "Taro",
        lastName: "Yamada",
        age: 28
    },
    success: function(responsePayload, statusMessage, xhrObject) {
        // responsePayload: サーバーから返されたデータ
        // statusMessage: "success", "notmodified" など
        // xhrObject: jQueryによってラップされたXMLHttpRequestオブジェクト
        console.log("ユーザー作成成功:", responsePayload);
        $("#output-area").html(`<p>ユーザー <strong>${responsePayload.firstName} ${responsePayload.lastName}</strong> が正常に登録されました！</p>`);
    },
    error: function(xhrObject, statusMessage, errorDescription) {
        console.error("ユーザー作成失敗:", statusMessage, errorDescription);
        $("#output-area").html(`<p style="color:red;">ユーザー登録中にエラーが発生しました: ${errorDescription}</p>`);
    }
});

例2: オブジェクト形式のデータ送信とエラーハンドリング

// GETパラメータとPOSTデータを同時に使用し、製品情報を更新する想定
$.ajax({
    url: "/api/update-product?category=electronics&id=123", // URLにGETパラメータを含める
    type: "PUT", // 更新にはPUTメソッドを使用（対応しているサーバーの場合）
    // jQueryはオブジェクトデータを自動的にURLエンコードされた文字列に変換します
    // 例: productName=Tablet&price=399.99&features=Lightweight&features=LongBattery
    data: {
        productName: "Tablet",
        price: 399.99,
        features: ["Lightweight", "LongBattery"] // 配列は複数の同名パラメータに変換されます
    },
    success: function(response, textStatus, jqXHR) {
        console.log("製品データ更新成功:", response);
        $("#output-area").html(`<p>製品 <strong>${response.productName}</strong> が $${response.price} で更新されました。</p>`);
    },
    error: function(jqXHR, textStatus, errorThrown) {
        // jqXHR: jQueryラップされたXMLHttpRequestオブジェクト
        // textStatus: "timeout", "error", "abort", "parsererror" など
        // errorThrown: "Not Found", "Internal Server Error" など
        console.error("製品データ更新失敗:", textStatus, errorThrown);
        $("#output-area").html(`<p style="color:red;">製品データ更新中にエラーが発生しました: ${errorThrown}</p>`);
    }
});

例3: URLを最初の引数として渡し、JSONデータを期待する（jQuery 1.5以降）

// /api/item/789 からアイテムの詳細をJSON形式で取得します
$.ajax("/api/item/789", {
    dataType: "json", // サーバーからの応答をJSONとしてパースするよう指定
    success: function(itemDetails, statusMsg, xhrRef) {
        // 例: サーバーが { "id": 789, "name": "Wireless Keyboard", "stock": 50 } を返す場合
        // dataTypeが"json"なので、itemDetailsは自動的にJavaScriptオブジェクトになっています
        console.log("アイテム詳細取得成功:", itemDetails);
        $("#output-area").html(`<p>アイテム名: <strong>${itemDetails.name}</strong>, 在庫数: ${itemDetails.stock}</p>`);
    },
    error: function(xhrRef, statusMsg, errorDesc) {
        console.error("アイテム詳細取得失敗:", errorDesc);
        $("#output-area").html(`<p style="color:red;">アイテム詳細の取得に失敗しました。</p>`);
    }
});

例4: クロスドメインJSONPリクエスト（同期リクエストは非推奨）

// 外部APIからJSONP形式でデータを取得します
// 注意: async: false はブラウザをフリーズさせる可能性があるため、特殊な理由がない限り避けるべきです。
$.ajax({
    url: "https://public-api.example.com/status?user=viewer&callback=?", // callback=? はJSONPの必須パターン
    async: true, // 通常は非同期に設定することを強く推奨します
    dataType: "jsonp", // JSONP形式でデータを要求
    success: function(apiResponse, statusInfo, xhrObj) {
        // 例: APIが { "serviceStatus": "Operational", "lastUpdate": "2023-10-27T10:00:00Z" } を返す場合
        console.log("APIステータス取得成功:", apiResponse);
        $("#output-area").append(`<p>サービスステータス: <strong>${apiResponse.serviceStatus}</strong>, 最終更新: ${new Date(apiResponse.lastUpdate).toLocaleString()}</p>`);
    },
    error: function(xhrObj, statusInfo, errorDetails) {
        console.error("JSONPリクエスト失敗:", errorDetails);
        $("#output-area").append(`<p style="color:red;">APIステータスの取得に失敗しました。</p>`);
    }
});

例5: 外部JavaScriptファイルのロード

// 外部のJavaScriptファイルを現在のドキュメントにロードして実行します
$.ajax({
    url: "/assets/analytics.js", // アプリケーション固有のスクリプトを想定
    dataType: "script", // ロードするファイルの種類をスクリプトと指定
    success: function() {
        console.log("analytics.js が正常にロードされ、実行されました。");
        // ロードされたスクリプト内で定義された関数や変数を利用できるようになります
        // if (typeof initializeAnalytics === 'function') {
        //     initializeAnalytics();
        // }
    },
    error: function(xhr, status, error) {
        console.error("スクリプトのロードに失敗しました:", error);
        $("#output-area").append(`<p style="color:red;">必要なスクリプトのロードに失敗しました。</p>`);
    }
});

タグ: jQuery AJAX javascript HTTPリクエスト非同期通信

8月3日 22:43 投稿

異端開発室