ステータスコードとレスポンスを返す（returnディレクティブ）

return ディレクティブは、クライアントへステータスコードとレスポンスを返すためのディレクティブです。リダイレクトや簡単なレスポンスの返却によく使用されます。このディレクティブが実行されると、リクエストの処理はその時点で終了します。ここでは、Nginx における return ディレクティブの使い方について解説します。

returnディレクティブの書式
returnディレクティブの設定例
動作確認

returnディレクティブの書式

return ディレクティブは、クライアントへステータスコードとレスポンスを返すためのディレクティブです。 return ディレクティブの書式は次の通りです。

Syntax:    return code [text];
           return code URL;
           return URL;
Default:   —
Context:   server, location, if

return ディレクティブは server、 locationコンテキスト、および if ディレクティブ内で使用できます。引数として、ステータスコード、テキスト、 URL を指定します。

クライアントからのリクエストに対して、処理結果を表す 3 桁の数値を返します。この数値を HTTP ステータスコードといいます。成功した場合は 200、リダイレクトする場合は 301 や 302、失敗した場合は 404 や 500 などを返します。

return ディレクティブでは、スタータスコードだけを返したり、スタータスコードと一緒に任意の文字列を返すことができます。

server {
  location /check1/ {
    return コード;
  }

  location /check2/ {
    return コード "文字列";
  }
}

リダイレクトを行う場合は、スタータスコードとリダイレクト先の URL を指定します。

server {
  location /check/ {
    return コード リダイレクト先URL;
  }
}

URL だけを指定した場合は、ステータスコード 302（リダイレクト）が使用されます。

server {
  location /check/ {
    return リダイレクト先URL;
  }
}

returnディレクティブの設定例

return ディレクティブの設定例をいくつか見ていきます。

http {
  server {
    location /check/ {
      default_type text/plain;
      return 200 "Ok";
    }
  }
}

return ディレクティブを使い、ステータスコードとして 200、文字列として "Ok" を返しています。 return を実行する前に default_type ディレクティブを使ってレスポンスをテキストファイルに設定しています。

※ default_type ディレクティブではなく add_header Content-Type text/plain; でも同じですが、 default_type の方がより確実です。

http {
  server {
    location /check/ {
      default_type text/html;
      charset utf-8;
      return 200 "<html><body><h1>成功です</h1></body></html>";
    }
  }
}

先ほどと基本的に同じですが、今度は文字列として HTML 文を返しています。そのため、return を実行する前に default_type ディレクティブを使ってレスポンスを HTML ファイルに設定し、 charsetディレクティブを使って文字コードを UTF-8 に設定しています。

http {
  server {
    if ($http_user_agent ~* "xxxx") {
      return 403;
    }
  }
}

組み込み変数の $http_user_agent が特定の値とマッチした場合に、 return ディレクティブを使い、ステータスコードとして 403 を返しています。

※ if ディレクティブの使い方については「条件分岐の使い方（ifディレクティブ）」を参照されてください。

http {
  server {
    if ($host = 'example.com') {
      return 301 https://www.example.com$request_uri;
    }
  }
}

組み込み変数の $host の値が "example.com" と等しい場合、 return ディレクティブを使い "www" を付けた "www.example.com" へ 301 リダイレクトしています。

動作確認

それでは実際に return ディレクティブの動作を確認してみます。 Nginx の設定ファイルである nginx.conf ファイルで http コンテキストに次のように設定しました。（必要な部分のみの抜粋です）。

http {
    server {
        location /check1/ {
            default_type text/html;
            charset utf-8;
            return 200 "<html><body><h1>成功です</h1></body></html>";
        }

        location /check2/ {
            return 403;
        }
    }
}

return ディレクティブを使用して、リクエストのパスが /check1/ と一致した場合、ステータスコード 200 と HTML 文を返します。また /check2/ と一致した場合、ステータスコードとして 403 を返します。

ブラウザを起動し、次の URL へアクセスします。

http://localhost/check1/

ステータスコードとして 200 と、設定した HTML 文が返されます。

returnディレクティブ(1)

次にブラウザを起動し、次の URL へアクセスします。

http://localhost/check2/

ステータスコードとして 403 が返されます。

returnディレクティブ(2)

このように return ディレクティブを使用することで、クライアントへステータスコードとレスポンスを返すことができます。

-- --

Nginx における return ディレクティブの使い方について解説しました。

( Written by Tatsuo Ikura )

著者 / TATSUO IKURA

これから IT 関連の知識を学ばれる方を対象に、色々な言語でのプログラミング方法や関連する技術、開発環境構築などに関する解説サイトを運営しています。