jQuery.ajax(settings)


version 1.0 以降

解説

HTTPリクエストを使用してデータを取得します。

このメソッドは、ajax の最も低レベルな実装です。

より使いやすく具体化された実装には、jQuery.get(url, [data], [handler], [dataType])jQuery.post(url, [data], [handler], [dataType])などがあります。 但し、このメソッドほど多くの機能は提供しませんので(例えば、エラーコールバック関数などは指定できません)、場合によって使い分けてください。 (もちろん、ajaxError(handler) 等のグローバルAjaxイベントを使えば、共通処理におけるハンドリングは可能です。)

このメソッドは XMLHttpRequest を返します。ほとんど使用することはありませんが、必要であれば、手動でリクエストを中止したりすることができます。

引数

  • options : リクエストのパラメータ。キーと値のハッシュ。
キー 初期値 説明
async Boolean true 非同期通信かどうかを指定します。非同期通信の場合は true、同期通信の場合は falseを設定します。
(同期通信の場合、通信中はブラウザがロックされ、すべての操作を受け付けなくなります。場合によって使い分けてください。)
beforeSend Function なし リクエストが送信される前に実行するコールバック関数を指定します。 引数にXMLHttpRequestオブジェクトが渡されますので、ヘッダをカスタマイズしたい場合などに使うことができます。 このコールバック関数が false を返すと、リクエストを中止します。
function (XMLHttpRequest) {
  // falseを返すと、リクエストを中止
}
cache Boolean true
dataType=="script"の場合はfalse
キャッシュを使用するかどうかを指定します。 キャッシュを有効にすると、リクエストに現在の時刻を使ったパラメータを付与します。 これにより,リクエスト毎に必ず異なった送信クエリが生成されるため、キャッシュされなくなります。
complete Function なし 通信が終了したときに実行するコールバック関数を指定します。 (success、errorのコールバック関数が実行された後に呼び出されます。) 引数にXMLHttpRequestオブジェクトと、リクエスト結果を表す文字列が渡されます。
リクエスト結果説明
success成功
error失敗
notmodified 更新されていない
timeoutタイムアウト
parsererrorデータパースエラー
function (XMLHttpRequest, status) {
  if (status == "success") {
      // リクエスト成功
  } else if (status == "error") {
      // リクエスト失敗
  } else if (status == "notmodified") {
      // 更新されていない
  } else if (status == "timeout") {
      // タイムアウト
  } else if (status == "parsererror") {
      // データパースエラー
  }
}
contentType String "application/x-www-form-urlencoded" 送信データのコンテンツタイプを指定します。
context
Object なし コールバック関数の context(this) を指定します。
$.ajax({
    url: urlString,
    context: document.getElementById("#contextID"),
    success: function(data, status, xhr) {
       // this は、#contextID 要素
       $("selector", this).append(data);
    }
});
data Object, String null サーバに送信するデータを指定します。 文字列でない場合は、自動的に application/x-www-form-urlencoded形式 にシリアライズします。 (この自動変換を行いたくない場合は、processDataオプションにfalseを指定してください。) オブジェクトを指定する場合、キーと値のペア(ハッシュ)を指定してください。 値が配列の場合は、同じキー名でシリアライズします。
例){key:["value1", "value2"]} => &key=value1&key=value2
dataFilter Function なし サーバから受信したデータをフィルタリングします。success コールバック関数に返す前に、データの無害化などを行うことができます。 dataFilter には、応答データと、応答データの形式 が渡されます。
function (data, type) {
    data; // data は、サーバから受信した応答データ
    type; // type は、応答データの形式

    // dataをフィルタリング
    ...
    // フィルタリングしたデータを返す。
    return data;
}
dataType String なし(自動判断) 期待するサーバの応答データの形式を指定します。指定された形式に従い、応答データを評価します。 指定しない場合は、応答データのMIMEタイプから自動的に判断します。
dataTypesuccessコールバック関数の第1引数に渡されるデータ
xmljQueryで処理可能なXMLドキュメントです。
htmlHTMLテキストです。scriptタグは評価されます。
script応答データをJavaScriptとして評価します。cacheオプションが指定されない限りキャッシュされません。
json応答データをJSONとして評価した、JavaScriptオブジェクトです。
jsonpJSONPを使用し、応答データを指定したコールバック関数によってJSONとして評価した、JavaScriptオブジェクトです。
textプレーンテキストです。
error Function なし 通信が失敗したときに実行するコールバック関数を指定します。 引数にXMLHttpRequestオブジェクトと、リクエスト結果を表す文字列、例外オブジェクトが渡されます。
function (XMLHttpRequest, status, errorThrown) {
    XMLHttpRequest; // XMLHttpRequestオブジェクト
    status; // status は、リクエスト結果を表す文字列
    errorThrown; // errorThrown は、例外オブジェクト
}
global Boolean true グローバルAjaxイベントを実行するかどうかを指定します。falseを指定すると実行しません。
グローバルAjaxイベント一覧
ifModified Boolean false データが更新されていた場合のみにデータを送信してもらうかどうかを指定します。 ("If-Modified-Since"ヘッダを設定します。)
jsonp String なし
(内部的に"callback"になる)
JSONPリクエストで使用するコールバック関数のパラメータ名を設定します。 何も指定をしないと、"callback"になります。
jsonpCallback String "jsonp" + エポック秒文字列 JSONPリクエストで使用するコールバック関数名を設定します。 何も指定をしないと、"jsonp" + エポック秒文字列になります。
password String null 認証が必要なHTTPリクエストを送信する場合のパスワードを指定します。
processData Boolean true dataオプションに指定したオブジェクトを、application/x-www-form-urlencoded形式にシリアライズするかどうかを指定します。 もし、そのままの形式で送信したい場合はfalseを指定してください。
scriptCharset String なし dataTypeオプションが "script"の場合や、内部的にscriptタグを生成して通信する場合(jsonp等)の、script読み込み時の文字コードを指定します。
success Function なし 通信が成功したときに実行するコールバック関数を指定します。 引数にdataTypeオプションに応じて評価された応答データ、リクエスト結果を表す文字列、XMLHttpRequest が渡されます。
function (data, status, xhr) {
    data; // data は、dataTypeに応じて評価された応答データ
    status; // status は、リクエスト結果を表す文字列
    xhr; // xhr は、XMLHttpRequest オブジェクト
}
timeout Number 0 タイムアウトの時間をミリ秒で指定します。
traditional Boolean なし
(内部的に false と同等)
true を指定すると、1.3 以前の古い形式でパラメータをシリアライズします。
詳細は、jQuery.param(obj, [traditional]) を参照してください。
type String "GET" "POST" もしくは "GET" を指定します。 ("PUT", "DELETE"も指定することができますが、すべてのブラウザに対応していません。)
url String 現在のページのURL(location.href) リクエスト先のURLを指定します。
username String null 認証が必要なHTTPリクエストを送信する場合のユーザ名を指定します。
xhr Function なし XMLHttpRequest オブジェクトを生成する関数を指定します。 例えば IE で Msxml2.XMLHTTP.6.0 を XMLHttpRequest として利用したい場合は、次のようにします。
function () {
    try {
        return new ActiveXObject("Msxml2.XMLHTTP.6.0");
    } catch(e){}
    try {
        return new ActiveXObject("Microsoft.XMLHTTP");
    } catch(e){}
    
    // default
    return new XMLHttpRequest();
}

戻り値

  • XMLHttpRequestオブジェクト

例1:Youtubeから検索結果をJSONPで取得し、表示します。

  • 検索文字列:テスト
  • 最大取得件数:5件
$.ajax({
    url: "http://gdata.youtube.com/feeds/api/videos",  // リクエストURL
    data: {                                            // 送信データ
        "vq": "テスト",            // 検索文字列
        "max-results": 5,         // 最大取得件数
        "alt": "json-in-script"   // jsonp
    },
    dataType: "jsonp",                                 // jsonp
    cache: true,                                       // キャッシュする
    success: function(data, status, xhr) {               // 通信成功時にデータを表示
        $("#test_result").append("----- Youtube検索結果 -----");
        $.each(data.feed.entry, function(i, item){
            var group = item.media$group;

            $("<div/>")
                .append($("<img/>").attr("src", group.media$thumbnail[0].url))
                .append("<br/>")
                .append(item.title.$t)
                .click(function(){window.open(group.media$player[0].url, null)})
            .appendTo("#test_result");
        });
    }
});


Etag のサポート

version 1.4 以降 では、Etag パラメータを判別するようになりました。

ifModified オプションが true の場合、レスポンスヘッダに Etag パラメータが存在した場合は、If-None-Match パラメータを送信します。