メインコンテンツまでスキップ

5. Request/Response Semantics (リクエスト/レスポンス セマンティクス)

CoAPは、HTTPと同様のリクエスト/レスポンスモデルで動作します: "クライアント (client)"ロールのCoAPエンドポイントが"サーバー (server)"に1つ以上のCoAPリクエストを送信し、サーバーはCoAPレスポンスを送信してリクエストを処理します。HTTPとは異なり、リクエストとレスポンスは、事前に確立された接続を介して送信されるのではなく、CoAPメッセージを介して非同期に交換されます。

5.1. Requests (リクエスト)​

CoAPリクエストは、リソースに適用されるメソッド、リソースの識別子、ペイロードとインターネットメディアタイプ (ある場合)、およびリクエストに関するオプションのメタデータで構成されます。

CoAPは、GET、POST、PUT、およびDELETEの基本メソッドをサポートしており、これらはHTTPに簡単にマッピングされます。これらは、HTTPと同じ安全 (取得のみ) および冪等 (同じ効果で複数回呼び出すことができる) のプロパティを持ちます ([RFC2616] のセクション9.1を参照)。GETメソッドは安全です。したがって、取得以外のリソースに対する他のアクションを実行してはなりません (MUST NOT)。GET、PUT、およびDELETEメソッドは、冪等になるように実行されなければなりません (MUST)。POSTは、その効果がオリジンサーバーによって決定され、ターゲットリソースに依存するため、冪等ではありません。通常、新しいリソースが作成されるか、ターゲットリソースが更新されます。

リクエストは、Confirmable (確認可能) またはNon-confirmable (確認不要) メッセージのCoAPヘッダーのCodeフィールドをMethod Codeに設定し、リクエスト情報を含めることによって開始されます。

リクエストで使用されるメソッドについては、セクション5.8で詳しく説明します。

5.2. Responses (レスポンス)​

リクエストを受信して解釈した後、サーバーはクライアントが生成したトークン (セクション5.3) によってリクエストに一致するCoAPレスポンスで応答します。これは、Confirmableメッセージを確認応答に一致させるMessage IDとは異なることに注意してください。

レスポンスは、CoAPヘッダーのCodeフィールドがResponse Codeに設定されていることによって識別されます。HTTPステータスコードと同様に、CoAPレスポンスコードは、リクエストを理解し、満たそうとする試みの結果を示します。これらのコードは、セクション5.9で完全に定義されています。CoAPヘッダーのCodeフィールドに設定されるResponse Code番号は、CoAP Response Code Registry (セクション12.1.2) で管理されています。

                              0
                              0 1 2 3 4 5 6 7
                             +-+-+-+-+-+-+-+-+
                             |class|  detail |
                             +-+-+-+-+-+-+-+-+

                  図 9: レスポンスコードの構造

8ビットのResponse Code番号の上位3ビットは、レスポンスのクラスを定義します。下位5ビットには分類の役割はありません。これらは、全体的なクラスに追加の詳細を与えます (図9)。

仕様およびプロトコル診断のための人間が読める表記として、Response Codeを含むCoAPコード番号は "c.dd" の形式で文書化されています。ここで、"c" は10進数のクラス、"dd" は2桁の10進数の詳細です。たとえば、"Forbidden" は 4.03 と記述され、16進数のコード値 0x83 (40x20+3) または10進数の 131 (432+3) を示します。

Response Codeには3つのクラスがあります:

2 - Success (成功): リクエストは正常に受信され、理解され、受け入れられました。

4 - Client Error (クライアントエラー): リクエストに誤った構文が含まれているか、満たすことができません。

5 - Server Error (サーバーエラー): サーバーは、明らかに有効なリクエストを満たすことができませんでした。

Response Codeは拡張可能に設計されています: エンドポイントによって認識されないClient ErrorまたはServer ErrorクラスのResponse Codeは、そのクラスの一般的なResponse Code (それぞれ4.00と5.00) と同等として扱われます。ただし、成功を示す一般的なResponse Codeはないため、エンドポイントによって認識されないSuccessクラスのResponse Codeは、それ以上の詳細なしにリクエストが成功したと判断するためにのみ使用できます。

可能なResponse Codeについては、セクション5.9で詳しく説明します。

レスポンスは複数の方法で送信できます。これらは、以下のサブセクションで定義されています。

5.2.1. Piggybacked (ピギーバック)​

最も基本的なケースでは、レスポンスは、リクエストを確認応答するAcknowledgementメッセージで直接運ばれます (これには、リクエストがConfirmableメッセージで運ばれたことが必要です)。これは "Piggybacked Response (ピギーバックレスポンス)" と呼ばれます。

レスポンスは、レスポンスが成功を示しているか失敗を示しているかに関係なく、Acknowledgementメッセージで返されます。事実上、レスポンスはAcknowledgementメッセージにピギーバックされ、レスポンスを返すために別のメッセージは必要ありません。

実装上の注意: プロトコルは、レスポンスをピギーバックするかどうか (つまり、分離レスポンスを送信するかどうか) の決定をサーバーに委ねています。クライアントは、どちらも受信できるように準備しなければなりません (MUST)。実装品質のレベルでは、サーバーが可能な限りピギーバックするコードを実装するという強い期待があります -- ネットワーク、およびクライアントとサーバーの両方でリソースを節約するためです。

5.2.2. Separate (分離)​

すべての場合においてピギーバックレスポンスを返すことができるとは限りません。たとえば、サーバーは、クライアントがリクエストメッセージを繰り返し再送するリスクを冒さずに、Acknowledgementメッセージを送り返すのを待つことができるよりも長く、要求されたリソースの表現を取得する必要がある場合があります (セクション4.8.2のPROCESSING_DELAYの議論も参照)。Non-confirmableメッセージで運ばれるリクエストへのレスポンスは、常に分離して送信されます (Acknowledgementメッセージがないため)。

サーバーでこれを実装する1つの方法は、リソース表現を取得する試みを開始し、その進行中に確認応答タイマーをタイムアウトさせることです。サーバーは、ピギーバックレスポンスがないことが事前にわかっている場合、すぐに確認応答を送信することもできます。どちらの場合も、確認応答は事実上、リクエストが後で処理されるという約束です。

サーバーがついにリソース表現を取得すると、レスポンスを送信します。このメッセージが失われないようにしたい場合は、サーバーからクライアントへのConfirmableメッセージとして送信され、サーバーが選択した新しいMessage IDをエコーするAcknowledgementでクライアントによって応答されます。(Non-confirmableメッセージとして送信することもできます。セクション5.2.3を参照してください。)

サーバーが分離レスポンスの使用を選択した場合、ConfirmableリクエストへのAcknowledgementをEmptyメッセージとして送信します。サーバーがEmpty Acknowledgementを送り返すと、クライアントが別の同一のリクエストを再送した場合でも、別のAcknowledgementでレスポンスを送り返してはなりません (MUST NOT)。再送されたリクエストが受信された場合 (おそらく元のAcknowledgementが遅延したため)、別のEmpty Acknowledgementが送信され、レスポンスは分離レスポンスとして送信されなければなりません (MUST)。

その後、サーバーがConfirmableレスポンスを送信する場合、そのレスポンスに対するクライアントのAcknowledgementもEmptyメッセージ (リクエストもレスポンスも運ばないメッセージ) でなければなりません (MUST)。サーバーは、一致するAcknowledgement (Response Codeまたはペイロードを黙って無視) またはResetメッセージでレスポンスの再送を停止しなければなりません (MUST)。

実装上の注意: 基礎となるデータグラムトランスポートはシーケンスを保持しない可能性があるため、レスポンスを運ぶConfirmableメッセージは、実際にはリクエストのAcknowledgementメッセージの前または後に到着する可能性があることに注意してください。再送シーケンスを終了する目的で、これも確認応答として機能します。また、CoAPプロトコル自体はここで特定の要求を行っていませんが、アプリケーションの観点から妥当な時間枠内にレスポンスが来るという期待があることにも注意してください。キープアライブメカニズムを実行するように指示できる基礎となるトランスポートプロトコルがないため、リクエスト元は、サーバーが破壊されたり、その他の理由でレスポンスを送信できなくなったりした場合に備えて、CoAPの再送タイマーとは無関係のタイムアウトを設定したい場合があります。

5.2.3. Non-confirmable (確認不要)​

リクエストメッセージがNon-confirmableの場合、レスポンスもNon-confirmableメッセージで返されるべきです (SHOULD)。ただし、エンドポイントは、Confirmableリクエストへの返信としてNon-confirmableレスポンス (Empty Acknowledgementメッセージの前または後) を、またはNon-confirmableリクエストへの返信としてConfirmableレスポンスを受信する準備ができていなければなりません (MUST)。

5.3. Request/Response Matching (リクエスト/レスポンス マッチング)​

レスポンスがどのように送信されるかに関係なく、クライアントによってリクエストに含まれるトークンと、対応するエンドポイントの追加のアドレス情報によって、リクエストに一致します。

5.3.1. Token (トークン)​

Tokenは、レスポンスとリクエストを一致させるために使用されます。トークン値は、0から8バイトのシーケンスです。(長さがゼロであっても、すべてのメッセージはトークンを運ぶことに注意してください。) すべてのリクエストは、サーバーが結果のレスポンスで (変更なしで) エコーしなければならない (MUST) クライアント生成トークンを運びます。

トークンは、同時リクエストを区別するためのクライアントローカル識別子として使用することを目的としています (セクション5.3を参照)。これは「リクエストID」と呼ばれることもありました。

クライアントは、特定の送信元/宛先エンドポイントペアに対して現在使用されているトークンが一意になるようにトークンを生成すべきです (SHOULD)。(クライアント実装は、毎回異なるエンドポイント (たとえば、異なる送信元ポート番号) を使用する場合、任意のリクエストに同じトークンを使用できることに注意してください。) 空のトークン値は、たとえば、宛先に対して他のトークンが使用されていない場合や、リクエストが宛先ごとに連続して行われ、ピギーバックレスポンスを受信する場合に適切です。ただし、これを実現するための実装戦略は複数あります。

トランスポート層セキュリティ (セクション9) を使用せずにリクエストを送信するクライアントは、レスポンスのなりすまし (セクション11.4) を防ぐために、重要でないランダム化されたトークンを使用すべきです (SHOULD)。トークンのこの保護的な使用が、最大8バイトのサイズが許可されている理由です。トークンに使用されるランダムコンポーネントの実際のサイズは、クライアントのセキュリティ要件と、レスポンスのなりすましによってもたらされる脅威のレベルによって異なります。一般的なインターネットに接続されているクライアントは、少なくとも32ビットのランダム性を使用すべきであり (SHOULD)、インターネットに直接接続されていないことが必ずしもなりすましに対する十分な保護ではないことに留意してください。(Message IDは通常順次割り当てられる、つまり推測可能であり、分離レスポンスをなりすますことで回避できるため、保護にはほとんど役立たないことに注意してください。) トークン長を最適化したいクライアントは、進行中の攻撃のレベルを検出し (たとえば、着信メッセージでの最近のトークン不一致を集計することによって)、トークン長を適切に上方修正したい場合もあります。[RFC4086] は、セキュリティのランダム性要件について説明しています。

生成しなかったトークンを受信するエンドポイントは、トークンを不透明なものとして扱い、その内容または構造についていかなる仮定も行ってはなりません (MUST)。

5.3.2. Request/Response Matching Rules (リクエスト/レスポンス マッチング ルール)​

レスポンスをリクエストに一致させるための正確なルールは次のとおりです:

  1. レスポンスの送信元エンドポイントは、元のリクエストの宛先エンドポイントと同じでなければなりません (MUST)。

  2. ピギーバックレスポンスでは、ConfirmableリクエストとAcknowledgementのMessage IDが一致しなければならず (MUST)、レスポンスと元のリクエストのトークンが一致しなければなりません (MUST)。分離レスポンスでは、レスポンスと元のリクエストのトークンのみが一致しなければなりません (MUST)。

レスポンスを運ぶメッセージが予期しない場合 (クライアントは、識別されたエンドポイントから、アドレス指定されたエンドポイントで、および/または特定のトークンを持つレスポンスを待っていない)、レスポンスは拒否されます (セクション4.2および4.3)。

実装上の注意: CONメッセージでレスポンスを受信するクライアントは、ACKを送信した直後にメッセージ状態をクリーンアップしたい場合があります。そのACKが失われ、サーバーがCONを再送した場合、クライアントはこのレスポンスを関連付ける状態をすでに持っていない可能性があり、再送は予期しないメッセージになります。クライアントは、これ以上の再送を受信しないようにResetメッセージを送信する可能性があります。この動作は正常であり、エラーを示すものではありません。(状態メモリの使用量において積極的に最適化されていないクライアントは、2番目のCONを再送として識別するメッセージ状態をまだ持っています。サーバーからのより多くのメッセージを実際に期待するクライアント [OBSERVE] は、いずれの場合も状態を保持する必要があります。)

5.4. Options (オプション)​

リクエストとレスポンスの両方に、1つ以上のオプションのリストを含めることができます。たとえば、リクエスト内のURIはいくつかのオプションで転送され、HTTPではHTTPヘッダーで運ばれるメタデータもオプションとして提供されます。

CoAPは、リクエストとレスポンスの両方で使用される単一のオプションセットを定義します:

  • Content-Format
  • ETag
  • Location-Path
  • Location-Query
  • Max-Age
  • Proxy-Uri
  • Proxy-Scheme
  • Uri-Host
  • Uri-Path
  • Uri-Port
  • Uri-Query
  • Accept
  • If-Match
  • If-None-Match
  • Size1

これらのオプションとそのプロパティのセマンティクスは、セクション5.10で詳しく定義されています。

すべてのオプションがすべてのメソッドおよびResponse Codeで使用できるように定義されているわけではありません。メソッドおよびResponse Codeに使用可能なオプションは、それぞれセクション5.8および5.9で定義されています。オプションがMethodまたはResponse Codeに対して定義されていない場合、送信者はそれを含めてはならず (MUST NOT)、受信者はそれを認識されないオプションのように扱わなければなりません (MUST)。

5.4.1. Critical/Elective (クリティカル/エレクティブ)​

オプションは、「クリティカル (critical)」または「エレクティブ (elective)」の2つのクラスのいずれかに分類されます。これらの違いは、エンドポイントによって認識されないオプションがどのように処理されるかです:

  • 受信時に、「エレクティブ」クラスの認識されないオプションは黙って無視されなければなりません (MUST)。

  • Confirmableリクエストで発生する「クリティカル」クラスの認識されないオプションは、4.02 (Bad Option) レスポンスの返却を引き起こさなければなりません (MUST)。このレスポンスには、認識されないオプションを説明する診断ペイロードを含めるべきです (SHOULD) (セクション5.5.2を参照)。

  • Confirmableレスポンスで発生するか、Acknowledgementでピギーバックされる「クリティカル」クラスの認識されないオプションは、レスポンスの拒否を引き起こさなければなりません (MUST) (セクション4.2)。

  • Non-confirmableメッセージで発生する「クリティカル」クラスの認識されないオプションは、メッセージの拒否を引き起こさなければなりません (MUST) (セクション4.3)。

クリティカルかエレクティブかに関係なく、オプションは決して「必須」ではない (常にオプションである) ことに注意してください。これらのルールは、実装が理解または実装していないオプションの処理を停止できるようにするために定義されています。

クリティカル/エレクティブルールは、プロキシを行わないエンドポイントに適用されます。プロキシは、セクション5.7で定義されているUnsafe/Safe-to-Forwardクラスに基づいてオプションを処理します。

5.4.2. Proxy Unsafe or Safe-to-Forward and NoCacheKey​

オプションがクリティカルまたはエレクティブとしてマークされていることに加えて、オプションは、プロキシがそれを認識しない場合にどのように処理するかによっても分類されます。この目的のために、オプションは転送に安全ではない (UnSafeが設定されている) か、転送しても安全 (Safe-to-Forward、UnSafeがクリアされている) のいずれかと見なすことができます。

さらに、Safe-to-Forwardとマークされたオプションの場合、オプション番号は、リクエスト内のCache-Key (セクション5.6) の一部となることを意図しているかどうかを示します。NoCacheKeyビットの一部が0の場合、そうです。すべてのNoCacheKeyビットが1の場合、そうではありません (セクション5.4.6を参照)。

注: Cache-Key指示は、特定のオプションをリクエストオプションとして実装せず、Unsafe/Safe-to-Forward指示のみに依存するプロキシにのみ関連します。たとえば、ETagの場合、リクエストオプションをCache-Keyの一部として実際に使用することは非常に非効率的ですが、ETagがプロキシによって実装されていない場合、レスポンスはリクエストオプションの存在に基づいて異なるため、これが行える最善の方法です。ETagリクエストオプションを実装するより便利なプロキシは、ETagをCache-Keyの一部として使用しません。

NoCacheKeyは3ビットで示されるため、8つのコードポイントのうち1つだけがNoCacheKeyとして認定され、8つのコードポイントのうち7つはより可能性が高いと思われるケースに残されます。

これらのクラスに関するプロキシの動作は、セクション5.7で定義されています。

5.4.3. Length (長さ)​

オプション値は、特定の長さを持つように定義されており、多くの場合、上限と下限の形式です。リクエスト内のオプション値の長さが定義された範囲外である場合、そのオプションは認識されないオプションのように扱わなければなりません (MUST) (セクション5.4.1を参照)。

5.4.4. Default Values (デフォルト値)​

オプションは、デフォルト値を持つように定義される場合があります。オプションの値がこのデフォルト値であることを意図している場合、そのオプションはメッセージに含まれるべきではありません (SHOULD NOT)。オプションが存在しない場合は、デフォルト値を想定しなければなりません (MUST)。

クリティカルオプションにデフォルト値がある場合、これは、メッセージにオプションがないことが、クリティカルオプションを認識しない実装と、この欠如をオプションのデフォルト値の存在として解釈する実装の両方によって適切に処理できるような方法で選択されます。

5.4.5. Repeatable Options (繰り返し可能なオプション)​

一部のオプションの定義では、それらのオプションが繰り返し可能であることが指定されています。繰り返し可能なオプションは、メッセージに1回以上含めることができます (MAY)。繰り返し可能でないオプションは、メッセージに2回以上含めてはなりません (MUST NOT)。

メッセージに、オプションが定義されているよりも多くの回数のオプションが含まれている場合、メッセージ内でその後に出現する各過剰なオプションは、認識されないオプションのように扱わなければなりません (MUST) (セクション5.4.1を参照)。

5.4.6. Option Numbers (オプション番号)​

オプションはオプション番号によって識別されます。これには、追加のセマンティクス情報も提供されます。たとえば、奇数はクリティカルオプションを示し、偶数はエレクティブオプションを示します。これは単なる慣習ではなく、プロトコルの機能であることに注意してください: オプションがエレクティブかクリティカルかは、そのオプション番号が偶数か奇数かによって完全に決定されます。

より一般的に言えば、オプション番号はビットマスクを使用して構築され、次の図に示すように、オプションがCriticalかElectiveか、UnsafeかSafe-to-Forwardか、およびSafe-to-Forwardの場合はCache-Key指示を提供するかどうかを示します。次のテキストでは、ビットマスクは、符号なし整数表現のオプション番号の最下位バイトに適用される単一バイトとして表されます。ビット7 (最下位ビット) が1の場合、オプションはCriticalです (同様に0の場合はElective)。ビット6が1の場合、オプションはUnsafeです (同様に0の場合はSafe-to-Forward)。ビット6が0の場合、つまりオプションがUnsafeでない場合、ビット3〜5がすべて1に設定されている場合にのみ、Cache-Keyではありません (NoCacheKey)。他のすべてのビットの組み合わせは、それが実際にCache-Keyであることを意味します。これらのオプションのクラスについては、次のセクションで説明します。

                       0   1   2   3   4   5   6   7
                     +---+---+---+---+---+---+---+---+
                     |           | NoCacheKey| U | C |
                     +---+---+---+---+---+---+---+---+

          図 10: オプション番号マスク (最下位バイト)

エンドポイントは、図11のCコードに相当するものを使用して、オプション番号 "onum" から特性を導き出すことができます。

   Critical = (onum & 1);
   UnSafe = (onum & 2);
   NoCacheKey = ((onum & 0x1e) == 0x1c);

図 11: オプション番号からの特性の決定

このドキュメントで定義されているオプションのオプション番号は、「CoAPオプション番号」レジストリ (セクション12.2) にリストされています。

5.5. Payloads and Representations (ペイロードと表現)​

リクエストとレスポンスの両方に、それぞれMethodまたはResponse Codeに応じて、ペイロードを含めることができます。MethodまたはResponse Codeがペイロードを持つように定義されていない場合、送信者はそれを含めてはならず (MUST NOT)、受信者はそれを無視しなければなりません (MUST)。

5.5.1. Representation (表現)​

成功を示すリクエストまたはレスポンスのペイロードは、通常、リソースの表現 (「リソース表現」) または要求されたアクションの結果 (「アクション結果」) です。その形式は、Content-Formatオプションで指定されたインターネットメディアタイプとコンテンツコーディングによって指定されます。このオプションがない場合、デフォルト値は想定されず、形式はアプリケーションによって推測される必要があります (たとえば、アプリケーションコンテキストから)。コンテンツタイプが指定されていない場合にのみ、ペイロードの「スニッフィング」を試みるべきです (SHOULD)。

実装上の注意: 実装品質のレベルでは、可能な限りリソース表現とともにContent-Format指示が提供されるという強い期待があります。これが「SHOULD」レベルの要件ではないのは、単にそれがプロトコル要件ではないためであり、この期待に違反できるケースを正確に概説することも困難だからです。

クライアントまたはサーバーエラーを示すレスポンスの場合、Content-Formatオプションが指定されている場合にのみ、ペイロードは要求されたアクションの結果の表現と見なされます。このオプションがない場合、ペイロードは診断ペイロード (セクション5.5.2) です。

5.5.2. Diagnostic Payload (診断ペイロード)​

Content-Formatオプションが指定されていない場合、クライアントまたはサーバーエラーを示すレスポンスのペイロードは、エラー状況を説明する短い人間が読める診断メッセージです。この診断メッセージは、UTF-8 [RFC3629] を使用して、より具体的にはNet-Unicode形式 [RFC5198] を使用してエンコードされなければなりません (MUST)。

メッセージは、HTTPステータス行のReason-Phraseに似ています。これはエンドユーザー向けではなく、デバッグ中に現在の英語仕様のコンテキストでそれを解釈する必要があるソフトウェアエンジニア向けです。したがって、言語タグ付けのメカニズムは必要なく、提供もされません。HTTPで通常行われていることとは対照的に、Response Code以外の追加情報がない場合、ペイロードは空であるべきです (SHOULD)。

5.5.3. Selected Representation (選択された表現)​

すべてのレスポンスが、リクエストによってアドレス指定されたリソースの表現を提供するペイロードを運ぶわけではありません。ただし、実際に同封されていたかどうかに関係なく、レスポンスに関連してそのような表現を参照できると便利な場合があります。

「選択された表現」という用語を使用して、対応するリクエストがGETメソッドを使用し、条件付きリクエストオプション (セクション5.10.8) を除外した場合に、成功したレスポンスで選択されていたターゲットリソースの現在の表現を参照します。

特定のレスポンスオプションは、選択された表現に関するメタデータを提供しますが、これは、一部の状態変更メソッドへのレスポンスのためにメッセージに含まれる表現とは異なる場合があります。本仕様で定義されているレスポンスオプションのうち、ETagレスポンスオプション (セクション5.10.6) のみが、選択された表現に関するメタデータとして定義されています。

5.5.4. Content Negotiation (コンテンツネゴシエーション)​

サーバーは、複数の表現形式のいずれかでリソースの表現を提供できる場合があります。クライアントからの詳細情報がない場合、サーバーは好みの形式で表現を提供します。

リクエストでAcceptオプション (セクション5.10.4) を使用することにより、クライアントは受信したいコンテンツ形式を示すことができます。

5.6. Caching (キャッシュ)​

CoAPエンドポイントは、将来の同等のリクエストでの応答時間とネットワーク帯域幅の消費を削減するために、レスポンスをキャッシュする場合があります (MAY)。

CoAPでのキャッシュの目的は、以前のレスポンスメッセージを再利用して現在のリクエストを満たすことです。場合によっては、ネットワークリクエストを必要とせずに、保存されたレスポンスを再利用できるため、遅延とネットワークラウンドトリップが削減されます。この目的のために「鮮度」メカニズムが使用されます (セクション5.6.1を参照)。新しいリクエストが必要な場合でも、以前のレスポンスのペイロードを再利用してリクエストを満たすことができる場合が多く、ネットワーク帯域幅の使用量が削減されます。この目的のために「検証」メカニズムが使用されます (セクション5.6.2を参照)。

HTTPとは異なり、CoAPレスポンスのキャッシュ可能性はリクエストメソッドには依存しませんが、Response Codeに依存します。各Response Codeのキャッシュ可能性は、セクション5.9のResponse Code定義とともに定義されています。成功を示し、エンドポイントによって認識されないResponse Codeは、キャッシュされてはなりません (MUST NOT)。

提示されたリクエストに対して、CoAPエンドポイントは、以下の場合を除き、保存されたレスポンスを使用してはなりません (MUST NOT):

  • 提示されたリクエストメソッドと、保存されたレスポンスを取得するために使用されたメソッドが一致し、

  • NoCacheKey (セクション5.4) としてマークされているか、キャッシュによって認識され、その指定されたキャッシュ動作に関して完全に解釈されたリクエストオプション (セクション5.10.6で説明されているETagリクエストオプションなど。セクション5.4.2も参照) の一致が必要ないことを除き、すべてのオプションが提示されたリクエストと保存されたレスポンスを取得するために使用されたリクエスト (リクエストURIを含む) の間で一致し、

  • 保存されたレスポンスが新鮮であるか、以下に定義されているように正常に検証されている。

キャッシュエントリの照合に使用されるリクエストオプションのセットは、まとめて「Cache-Key」とも呼ばれます。coapおよびcoaps以外のURIスキームの場合、リクエストURIを構成するオプションの照合は、URIスキームに固有のルールの下で実行される場合があります。

5.6.1. Freshness Model (鮮度モデル)​

レスポンスがキャッシュ内で「新鮮」である場合、オリジンサーバーに連絡することなく後続のリクエストを満たすために使用できるため、効率が向上します。

鮮度を決定するメカニズムは、オリジンサーバーがMax-Ageオプション (セクション5.10.5を参照) を使用して、将来の明示的な有効期限を提供することです。Max-Ageオプションは、その年齢が指定された秒数を超えた後、レスポンスが新鮮ではないと見なされることを示します。

Max-Ageオプションのデフォルト値は60です。したがって、キャッシュ可能なレスポンスに存在しない場合、その年齢が60秒を超えた後、レスポンスは新鮮ではないと見なされます。オリジンサーバーがキャッシュを防ぎたい場合は、0秒の値を持つMax-Ageオプションを明示的に含めなければなりません (MUST)。

クライアントが新鮮な保存されたレスポンスを持っており、その保存されたレスポンスのリクエストと一致する新しいリクエストを行う場合、新しいレスポンスは古いレスポンスを無効にします。

5.6.2. Validation Model (検証モデル)​

エンドポイントがGETリクエストに対して1つ以上の保存されたレスポンスを持っているが、それらのいずれも使用できない (たとえば、新鮮ではないため) 場合、GETリクエストでETagオプション (セクション5.10.6) を使用して、オリジンサーバーに使用する保存されたレスポンスを選択し、その鮮度を更新する機会を与えることができます。このプロセスは、保存されたレスポンスの「検証」または「再検証」として知られています。

このようなリクエストを送信する場合、エンドポイントは、適用可能な各保存されたレスポンスのエンティティタグを指定するETagオプションを追加すべきです (SHOULD)。

2.03 (Valid) レスポンスは、レスポンスのETagオプションで指定されたエンティティタグによって識別される保存されたレスポンスが、セクション5.9.1.3で説明されているように更新した後に再利用できることを示します。

その他のResponse Codeは、リクエストで指名された保存されたレスポンスがいずれも適切ではないことを示します。代わりに、レスポンスを使用してリクエストを満たすべきであり (SHOULD)、保存されたレスポンスを置き換えることができます (MAY)。

5.7. Proxying (プロキシ)​

プロキシは、CoAPクライアントから委任されて、その代わりにリクエストを実行できるCoAPエンドポイントです。これは、たとえば、他の方法ではリクエストを行えない場合や、応答時間とネットワーク帯域幅またはエネルギー消費を削減するためにキャッシュからレスポンスを提供する場合に役立ちます。

制約されたRESTful環境の全体的なアーキテクチャでは、プロキシはまったく異なる目的を果たすことができます。プロキシはクライアントによって明示的に選択できます。この役割を「フォワードプロキシ (forward-proxy)」と呼びます。プロキシは、オリジンサーバーの代わりに立つように挿入することもできます。この役割を「リバースプロキシ (reverse-proxy)」と呼びます。この区別とは直交して、プロキシはCoAPリクエストからCoAPリクエストにマッピングする (CoAP-to-CoAPプロキシ) か、異なるプロトコルから、または異なるプロトコルへ変換する (「クロスプロキシ (cross-proxy)」) ことができます。これらの用語の完全な定義は、セクション1.2に記載されています。

注: 本仕様の用語は、より広いWebアプリケーション環境で使用される用語と文化的に互換性があるように選択されていますが、必ずしもすべての詳細で一致するわけではありません (これは、制約されたRESTful環境に関連しない可能性さえあります)。用語の構成要素 (「フォワード」、「リバース」、または「クロス」など) にあまり多くのセマンティクスを帰属させるべきではありません。

HTTPプロキシは、HTTPプロキシとして機能するだけでなく、多くの場合、プロキシを介してエンドツーエンドのトランスポート層セキュリティを有効にするためのトランスポートプロトコルプロキシ機能 (「CONNECT」) を提供します。UDPパケットの転送は制約されたRESTful環境ではあまり価値がない可能性が高いため、本仕様ではCoAP-to-CoAPプロキシに対してそのような機能は定義されていません。クロスプロキシのケースについては、セクション10.2.7も参照してください。

クライアントがプロキシを使用して、安全なURIスキーム (「coaps」や「https」など) を使用するリクエストを行う場合、クライアントとプロキシの間の区間で同等の下位層セキュリティが使用されている場合を除き、プロキシへのリクエストはDTLSを使用して送信されるべきです (SHOULD)。

5.7.1. Proxy Operation (プロキシ操作)​

プロキシは通常、クライアントから受信したリクエストに基づいて、宛先に対して行うリクエストの潜在的なリクエストパラメータを決定する方法を必要とします。この方法はフォワードプロキシに対しては完全に指定されていますが、リバースプロキシの場合は特定の構成に依存する場合があります。特に、リバースプロキシのクライアントは通常、宛先のロケータを示さないため、リバースプロキシで何らかの形式の名前空間変換が必要になります。ただし、プロキシの操作のいくつかの側面は、そのすべての形式に共通しています。

プロキシがキャッシュを使用しない場合、変換されたリクエストを決定された宛先に転送するだけです。それ以外の場合、キャッシュを使用するが、変換されたリクエストと一致し、新鮮であると見なされる保存されたレスポンスがない場合は、セクション5.6に従ってキャッシュを更新する必要があります。プロキシが認識するリクエスト内のオプションについては、そのオプションがキャッシュされた値の検索に使用されるキーの一部として機能することを意図しているかどうかを知っています。たとえば、異なるUri-Path値のリクエストは異なるリソースをアドレス指定するため、Uri-Path値は常にCache-Keyの一部ですが、たとえば、Token値は決してCache-Keyの一部ではありません。プロキシが認識しないがオプション番号でSafe-to-Forwardとマークされているオプションの場合、オプションはCache-Keyに含まれるか (NoCacheKeyがすべて設定されていない)、含まれないか (NoCacheKeyがすべて設定されている) も示します。(認識されず、Unsafeとマークされているオプションは、4.02 Bad Optionにつながります。)

宛先へのリクエストがタイムアウトした場合、5.04 (Gateway Timeout) レスポンスが返されなければなりません (MUST)。宛先へのリクエストが、プロキシによって処理できないレスポンスを返した場合 (たとえば、認識されないクリティカルオプションやメッセージフォーマットエラーのため)、5.02 (Bad Gateway) レスポンスが返されなければなりません (MUST)。それ以外の場合、プロキシはレスポンスをクライアントに返します。

レスポンスがキャッシュから生成される場合、生成された (または暗黙の) Max-Ageオプションは、リソース表現がキャッシュに費やした時間を考慮して、サーバーによって最初に設定されたmax-ageを延長してはなりません (MUST NOT)。たとえば、Max-Ageオプションは、次の式を使用して、各レスポンスに対してプロキシによって調整できます:

proxy-max-age = original-max-age - cache-age

たとえば、20秒前に更新され、元のMax-Ageが60秒であったプロキシリソースに対してリクエストが行われた場合、そのリソースのプロキシmax-ageは現在40秒です。オリジンサーバーからの途中の潜在的なネットワーク遅延を考慮して、プロキシは提供されるmax-age値について保守的であるべきです。

プロキシリクエストに存在するすべてのオプションは、プロキシで処理されなければなりません (MUST)。プロキシによって認識されないリクエスト内のUnsafeオプションは、プロキシによって返される4.02 (Bad Option) レスポンスにつながらなければなりません (MUST)。CoAP-to-CoAPプロキシは、認識しないすべてのSafe-to-Forwardオプションをオリジンサーバーに転送しなければなりません (MUST)。同様に、CoAP-to-CoAPプロキシサーバーによって認識されないレスポンス内のUnsafeオプションは、5.02 (Bad Gateway) レスポンスにつながらなければなりません (MUST)。ここでも、認識されないSafe-to-Forwardオプションは転送されなければなりません (MUST)。

CoAPとHTTP間のクロスプロトコルプロキシングに関する追加の考慮事項については、セクション10で説明します。

5.7.2. Forward-Proxies (フォワードプロキシ)​

CoAPは、(あたかも) オリジンサーバーに対して行われるリクエストと、フォワードプロキシを介して行われるリクエストを区別します。フォワードプロキシへのCoAPリクエストは、フォワードプロキシエンドポイントへの通常のConfirmableまたはNon-confirmableリクエストとして行われますが、リクエストURIを別の方法で指定します: プロキシリクエストのリクエストURIはProxy-Uriオプション (セクション5.10.2を参照) で文字列として指定されますが、オリジンサーバーへのリクエストのリクエストURIはUri-Host、Uri-Port、Uri-Path、およびUri-Queryオプション (セクション5.10.1を参照) に分割されます。あるいは、プロキシリクエスト内のURIは、Proxy-Schemeオプションと言及された分割オプションから組み立てることができます。

エンドポイントに対してプロキシリクエストが行われ、エンドポイントがリクエストURIのプロキシとして機能する意思がないか、できない場合、5.05 (Proxying Not Supported) レスポンスを返さなければなりません (MUST)。権限 (ホストとポート) がプロキシエンドポイント自体を識別していると認識される場合 (セクション5.10.2を参照)、リクエストはローカル (非プロキシ) リクエストとして扱われなければなりません (MUST)。

プロキシがプロキシリクエストを別のプロキシに転送するように構成されていない限り、次のようにリクエストを変換しなければなりません (MUST): リクエストURIのスキームは、発信プロトコルとその詳細を定義します (たとえば、CoAPは「coap」スキームの場合はUDP経由で、「coaps」スキームの場合はDTLS経由で使用されます)。CoAP-to-CoAPプロキシの場合、オリジンサーバーのIPアドレスとポートはリクエストURIの権限コンポーネントによって決定され、リクエストURIはデコードされてUri-Host、Uri-Port、Uri-Path、およびUri-Queryオプションに分割されます。これによりProxy-UriまたはProxy-Schemeオプションが消費されるため、オリジンサーバーには転送されません。

5.7.3. Reverse-Proxies (リバースプロキシ)​

リバースプロキシはProxy-UriまたはProxy-Schemeオプションを使用しませんが、リクエスト内の情報とその構成内の情報からリクエストの宛先 (次のホップ) を決定する必要があります。たとえば、リバースプロキシは、リソース検出を通じてその存在を知った後、あたかもそれらが独自のリソースであるかのようにさまざまなリソースを提供する場合があります。リバースプロキシは、これらのリソースを識別するURIの名前空間を自由に構築できます。リバースプロキシは、たとえば、ホスト識別子とポート番号を提供されるリソースのURIパスに埋め込むことによって、クライアントにリクエストの行き先をより細かく制御させる名前空間を構築することもできます。

レスポンスを処理する際、リバースプロキシは、異なるソースからのETagオプション値が、クライアントに提供される1つのリソース上で混在しないように注意する必要があります。多くの場合、ETagは変更せずに転送できます。リバースプロキシによって提供されるリソースからそのさまざまなオリジンサーバーによって提供されるリソースへのマッピングが一意でない場合、リバースプロキシは新しいETagを生成し、このオプションのセマンティクスが適切に保持されるようにする必要がある場合があります。

5.8. Method Definitions (メソッド定義)​

このセクションでは、各メソッドとその動作について定義します。認識されないかサポートされていないMethod Codeを持つリクエストは、4.05 (Method Not Allowed) ピギーバックレスポンスを生成しなければなりません (MUST)。

5.8.1. GET​

GETメソッドは、リクエストURIによって識別されるリソースに現在対応している情報の表現を取得します。リクエストにAcceptオプションが含まれている場合、それはレスポンスの好ましいコンテンツ形式を示します。リクエストにETagオプションが含まれている場合、GETメソッドはETagが検証されることを要求し、検証が失敗した場合にのみ表現が転送されます。成功すると、2.05 (Content) または2.03 (Valid) Response Codeがレスポンスに存在するはずです (SHOULD)。

GETメソッドは安全で冪等です。

5.8.2. POST​

POSTメソッドは、リクエストに含まれる表現が処理されることを要求します。POSTメソッドによって実行される実際の機能は、オリジンサーバーによって決定され、ターゲットリソースに依存します。通常、新しいリソースが作成されるか、ターゲットリソースが更新されます。

サーバー上でリソースが作成された場合、サーバーによって返されるレスポンスは2.01 (Created) Response Codeを持つべきであり (SHOULD)、1つ以上のLocation-Pathおよび/またはLocation-Queryオプション (セクション5.10.7) のシーケンスに新しいリソースのURIを含めるべきです (SHOULD)。POSTが成功したが、サーバー上に新しいリソースが作成されなかった場合、レスポンスは2.04 (Changed) Response Codeを持つべきです (SHOULD)。POSTが成功し、ターゲットリソースが削除された場合、レスポンスは2.02 (Deleted) Response Codeを持つべきです (SHOULD)。

POSTは安全でも冪等でもありません。

5.8.3. PUT​

PUTメソッドは、リクエストURIによって識別されるリソースを、同封された表現で更新または作成することを要求します。提供されている場合、表現形式はContent-Formatオプションで指定されたメディアタイプとコンテンツコーディングによって指定されます。

リソースがリクエストURIに存在する場合、同封された表現はそのリソースの変更されたバージョンと見なされるべきであり (SHOULD)、2.04 (Changed) Response Codeが返されるべきです (SHOULD)。リソースが存在しない場合、サーバーはそのURIで新しいリソースを作成してもよく (MAY)、その結果2.01 (Created) Response Codeになります。リソースを作成または変更できなかった場合は、適切なエラーResponse Codeを送信すべきです (SHOULD)。

リクエストにIf-Match (セクション5.10.8.1を参照) またはIf-None-Match (セクション5.10.8.2を参照) オプションを含めることで、PUTに対するさらなる制限を行うことができます。

PUTは安全ではありませんが、冪等です。

5.8.4. DELETE​

DELETEメソッドは、リクエストURIによって識別されるリソースが削除されることを要求します。成功した場合、またはリクエストの前にリソースが存在しなかった場合は、2.02 (Deleted) Response Codeを使用すべきです (SHOULD)。

DELETEは安全ではありませんが、冪等です。

5.9. Response Code Definitions (レスポンスコード定義)​

各Response Codeについては以下で説明し、レスポンスに必要なオプションを含めます。必要に応じて、一部のコードはHTTP [RFC2616] の関連するResponse Codeに関して指定されます。これは、そのような関係がセクション10で指定されたHTTPマッピングを変更することを意味するものではありません。

5.9.1. Success 2.xx (成功 2.xx)​

このクラスのResponse Codeは、クライアントのリクエストが正常に受信され、理解され、受け入れられたことを示します。

5.9.1.1. 2.01 Created (作成済み)​

HTTP 201 "Created" と同様ですが、POSTおよびPUTリクエストへの応答としてのみ使用されます。レスポンスとともに返されるペイロードがある場合、それはアクション結果の表現です。

レスポンスに1つ以上のLocation-Pathおよび/またはLocation-Queryオプションが含まれている場合、これらのオプションの値は、リソースが作成された場所を指定します。それ以外の場合、リソースはリクエストURIで作成されました。このレスポンスを受信するキャッシュは、作成されたリソースの保存されたレスポンスを新鮮ではないとしてマークしなければなりません (MUST)。

このレスポンスはキャッシュできません。

5.9.1.2. 2.02 Deleted (削除済み)​

このResponse CodeはHTTP 204 "No Content" に似ていますが、DELETEや、特定の状況ではPOSTなど、リソースが利用できなくなるリクエストへの応答としてのみ使用されます。レスポンスとともに返されるペイロードがある場合、それはアクション結果の表現です。

このレスポンスはキャッシュできません。ただし、キャッシュは、削除されたリソースの保存されたレスポンスを新鮮ではないとしてマークしなければなりません (MUST)。

5.9.1.3. 2.03 Valid (有効)​

このResponse CodeはHTTP 304 "Not Modified" に関連していますが、含まれているETagオプションによって識別されるエンティティタグによって識別されるレスポンスが有効であることを示すためにのみ使用されます。したがって、レスポンスにはETagオプションを含めなければならず (MUST)、ペイロードを含めてはなりません (MUST NOT)。

ETagレスポンスオプションを認識して処理するキャッシュが2.03 (Valid) レスポンスを受信すると、レスポンスに含まれるMax-Ageオプションの値 (明示的、またはデフォルト値として暗黙的。セクション5.6.2も参照) で保存されたレスポンスを更新しなければなりません (MUST)。レスポンスに存在するSafe-to-Forwardオプションの各タイプについて、保存されたレスポンスに存在するこのタイプのオプションの (おそらく空の) セットは、受信したレスポンス内のこのタイプのオプションのセットに置き換えられなければなりません (MUST)。(Unsafeオプションは、オプションによって定義される同様のオプション固有の処理をトリガーする場合があります。)

5.9.1.4. 2.04 Changed (変更済み)​

このResponse CodeはHTTP 204 "No Content" に似ていますが、POSTおよびPUTリクエストへの応答としてのみ使用されます。レスポンスとともに返されるペイロードがある場合、それはアクション結果の表現です。

このレスポンスはキャッシュできません。ただし、キャッシュは、変更されたリソースの保存されたレスポンスを新鮮ではないとしてマークしなければなりません (MUST)。

5.9.1.5. 2.05 Content (コンテンツ)​

このResponse CodeはHTTP 200 "OK" に似ていますが、GETリクエストへの応答としてのみ使用されます。

レスポンスとともに返されるペイロードは、ターゲットリソースの表現です。

このレスポンスはキャッシュ可能です: キャッシュはMax-Ageオプションを使用して鮮度を決定し (セクション5.6.1を参照)、(存在する場合) ETagオプションを検証に使用できます (セクション5.6.2を参照)。

5.9.2. Client Error 4.xx (クライアントエラー 4.xx)​

このクラスのResponse Codeは、クライアントが誤ったと思われる場合を対象としています。これらのResponse Codeは、任意のリクエストメソッドに適用できます。

サーバーは、セクション5.5.2で詳しく説明されている条件下で診断ペイロードを含めるべきです (SHOULD)。

このクラスのレスポンスはキャッシュ可能です: キャッシュはMax-Ageオプションを使用して鮮度を決定できます (セクション5.6.1を参照)。これらは検証できません。

5.9.2.1. 4.00 Bad Request (不正なリクエスト)​

このResponse CodeはHTTP 400 "Bad Request" に似ています。

5.9.2.2. 4.01 Unauthorized (未承認)​

クライアントは、要求されたアクションを実行する権限がありません。クライアントは、最初にサーバーに対する認証ステータスを改善せずにリクエストを繰り返すべきではありません (SHOULD NOT)。これに使用できる具体的なメカニズムは、このドキュメントの範囲外です。セクション9も参照してください。

5.9.2.3. 4.02 Bad Option (不正なオプション)​

1つ以上の認識されないオプションまたは不正な形式のオプションのため、サーバーはリクエストを理解できませんでした。クライアントは、変更せずにリクエストを繰り返すべきではありません (SHOULD NOT)。

5.9.2.4. 4.03 Forbidden (禁止)​

このResponse CodeはHTTP 403 "Forbidden" に似ています。

5.9.2.5. 4.04 Not Found (未検出)​

このResponse CodeはHTTP 404 "Not Found" に似ています。

5.9.2.6. 4.05 Method Not Allowed (メソッド不許可)​

このResponse CodeはHTTP 405 "Method Not Allowed" に似ていますが、"Allow" ヘッダーフィールドに相当するものはありません。

5.9.2.7. 4.06 Not Acceptable (受理不可)​

このResponse CodeはHTTP 406 "Not Acceptable" に似ていますが、レスポンスエンティティはありません。

5.9.2.8. 4.12 Precondition Failed (前提条件失敗)​

このResponse CodeはHTTP 412 "Precondition Failed" に似ています。

5.9.2.9. 4.13 Request Entity Too Large (リクエストエンティティが大きすぎる)​

このResponse CodeはHTTP 413 "Request Entity Too Large" に似ています。

サーバーがこの情報を利用可能にする立場にない場合を除き、サーバーが処理できる最大リクエストエンティティサイズを示すために、レスポンスにはSize1オプション (セクション5.10.9) を含めるべきです (SHOULD)。

5.9.2.10. 4.15 Unsupported Content-Format (サポートされていないコンテンツ形式)​

このResponse CodeはHTTP 415 "Unsupported Media Type" に似ています。

5.9.3. Server Error 5.xx (サーバーエラー 5.xx)​

このクラスのResponse Codeは、サーバーがエラーを起こした、またはリクエストを実行できないことを認識している場合を示します。これらのResponse Codeは、任意のリクエストメソッドに適用できます。

サーバーは、セクション5.5.2で詳しく説明されている条件下で診断ペイロードを含めるべきです (SHOULD)。

このクラスのレスポンスはキャッシュ可能です: キャッシュはMax-Ageオプションを使用して鮮度を決定できます (セクション5.6.1を参照)。これらは検証できません。

5.9.3.1. 5.00 Internal Server Error (内部サーバーエラー)​

このResponse CodeはHTTP 500 "Internal Server Error" に似ています。

5.9.3.2. 5.01 Not Implemented (未実装)​

このResponse CodeはHTTP 501 "Not Implemented" に似ています。

5.9.3.3. 5.02 Bad Gateway (不正なゲートウェイ)​

このResponse CodeはHTTP 502 "Bad Gateway" に似ています。

5.9.3.4. 5.03 Service Unavailable (サービス利用不可)​

このResponse CodeはHTTP 503 "Service Unavailable" に似ていますが、"Retry-After" ヘッダーフィールドの代わりにMax-Ageオプションを使用して、再試行するまでの秒数を示します。

5.9.3.5. 5.04 Gateway Timeout (ゲートウェイタイムアウト)​

このResponse CodeはHTTP 504 "Gateway Timeout" に似ています。

5.9.3.6. 5.05 Proxying Not Supported (プロキシ未サポート)​

サーバーは、Proxy-Uriオプションで指定されたURI、またはProxy-Scheme (セクション5.10.2を参照) を使用するURIのフォワードプロキシとして機能できないか、機能する意思がありません。

5.10. Option Definitions (オプション定義)​

個々のCoAPオプションを表4にまとめ、このセクションのサブセクションで説明します。

この表では、C、U、およびN列は、それぞれCritical、UnSafe、およびNoCacheKeyプロパティを示しています。NoCacheKeyは、Safe-to-Forward (UnSafeとマークされていない) オプションに対してのみ意味を持つため、UnSafeオプションの場合、列はダッシュで埋められます。

   +-----+---+---+---+---+----------------+--------+--------+----------+
   | No. | C | U | N | R | Name           | Format | Length | Default  |
   +-----+---+---+---+---+----------------+--------+--------+----------+
   |   1 | x |   |   | x | If-Match       | opaque | 0-8    | (none)   |
   |   3 | x | x | - |   | Uri-Host       | string | 1-255  | (see     |
   |     |   |   |   |   |                |        |        | below)   |
   |   4 |   |   |   | x | ETag           | opaque | 1-8    | (none)   |
   |   5 | x |   |   |   | If-None-Match  | empty  | 0      | (none)   |
   |   7 | x | x | - |   | Uri-Port       | uint   | 0-2    | (see     |
   |     |   |   |   |   |                |        |        | below)   |
   |   8 |   |   |   | x | Location-Path  | string | 0-255  | (none)   |
   |  11 | x | x | - | x | Uri-Path       | string | 0-255  | (none)   |
   |  12 |   |   |   |   | Content-Format | uint   | 0-2    | (none)   |
   |  14 |   | x | - |   | Max-Age        | uint   | 0-4    | 60       |
   |  15 | x | x | - | x | Uri-Query      | string | 0-255  | (none)   |
   |  17 | x |   |   |   | Accept         | uint   | 0-2    | (none)   |
   |  20 |   |   |   | x | Location-Query | string | 0-255  | (none)   |
   |  35 | x | x | - |   | Proxy-Uri      | string | 1-1034 | (none)   |
   |  39 | x | x | - |   | Proxy-Scheme   | string | 1-255  | (none)   |
   |  60 |   |   | x |   | Size1          | uint   | 0-4    | (none)   |
   +-----+---+---+---+---+----------------+--------+--------+----------+

             C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable

                             表 4: オプション

5.10.1. Uri-Host, Uri-Port, Uri-Path, and Uri-Query​

Uri-Host、Uri-Port、Uri-Path、およびUri-Queryオプションは、CoAPオリジンサーバーへのリクエストのターゲットリソースを指定するために使用されます。オプションは、パーセントエンコーディングがオプション値に表示されない方法でリクエストURIのさまざまなコンポーネントをエンコードし、関係するすべてのエンドポイントで完全なURIを再構築できるようにします。CoAP URIの構文はセクション6で定義されています。

URIをオプションに解析する手順は、セクション6.4で定義されています。これらの手順により、0個以上のUri-Host、Uri-Port、Uri-Path、およびUri-Queryオプションがリクエストに含まれ、各オプションは次の値を保持します:

  • Uri-Hostオプションは、要求されているリソースのインターネットホストを指定します。

  • Uri-Portオプションは、リソースのトランスポート層ポート番号を指定します。

  • 各Uri-Pathオプションは、リソースへの絶対パスの1つのセグメントを指定します。

  • 各Uri-Queryオプションは、リソースをパラメータ化する1つの引数を指定します。

注: フラグメント ([RFC3986]、セクション3.5) はリクエストURIの一部ではないため、CoAPリクエストでは送信されません。

Uri-Hostオプションのデフォルト値は、リクエストメッセージの宛先IPアドレスを表すIPリテラルです。同様に、Uri-Portオプションのデフォルト値は、宛先UDPポートです。Uri-HostおよびUri-Portオプションのデフォルト値は、ほとんどのサーバーへのリクエストで十分です。明示的なUri-HostおよびUri-Portオプションは、通常、エンドポイントが複数の仮想サーバーをホストする場合に使用されます。

Uri-PathおよびUri-Queryオプションには、任意の文字シーケンスを含めることができます。パーセントエンコーディングは実行されません。Uri-Pathオプションの値は "." または ".." であってはなりません (MUST NOT) (リクエストURIはオプションに解析される前に解決される必要があるため)。

オプションからリクエストURIを構築する手順は、セクション6.5で定義されています。実装は必ずしもURIを構築する必要はないことに注意してください。個々のオプションを調べることでターゲットリソースを検索するだけです。

例は付録Bにあります。

5.10.2. Proxy-Uri and Proxy-Scheme​

Proxy-Uriオプションは、フォワードプロキシへのリクエストを行うために使用されます (セクション5.7を参照)。フォワードプロキシは、リクエストを転送するか、有効なキャッシュからサービスを提供してレスポンスを返すように要求されます。

オプション値はabsolute-URI ([RFC3986]、セクション4.3) です。

フォワードプロキシは、リクエストを別のプロキシに転送するか、absolute-URIで指定されたサーバーに直接転送できることに注意してください (MAY)。リクエストループを回避するために、プロキシは、エイリアス、ローカルバリエーション、および数値IPアドレスを含む、すべてのサーバー名を認識できなければなりません (MUST)。

リクエストのフォワードプロキシとして機能できないか、機能する意思がないProxy-Uriオプションを含むリクエストを受信するエンドポイントは、5.05 (Proxying Not Supported) レスポンスの返却を引き起こさなければなりません (MUST)。

Proxy-Uriオプションは、Uri-Host、Uri-Port、Uri-Path、またはUri-Queryオプションのいずれよりも優先されなければなりません (MUST) (Proxy-Uriオプションを含むリクエストには、これらを含めてはなりません (MUST NOT))。

多くのプロキシクライアントを簡素化するための特例として、absolute-URIはUri-*オプションから構築できます。Proxy-Schemeオプションが存在する場合、absolute-URIは次のように構築されます: セクション6.5で定義されているように、Uri-*オプションからCoAP URIが構築されます。結果のURIで、最初のスキームから次のコロンまで (コロンは含まない) が、Proxy-Schemeオプションの内容に置き換えられます。このケースは、スキームコンポーネント以外の目的のURIのコンポーネントが実際にUri-*オプションを使用して表現できる場合にのみ適用可能であることに注意してください。たとえば、権限にuserinfoコンポーネントを持つURIを表現するには、Proxy-Uriのみを使用できます。

5.10.3. Content-Format​

Content-Formatオプションは、メッセージペイロードの表現形式を示します。表現形式は、「CoAPコンテンツ形式」レジストリ (セクション12.3) で定義されている数値のContent-Format識別子として指定されます。オプションがない場合、デフォルト値は想定されません。つまり、表現メッセージペイロードの表現形式は不確定です (セクション5.5)。

5.10.4. Accept​

CoAP Acceptオプションを使用して、クライアントが受け入れ可能なContent-Formatを示すことができます。表現形式は、「CoAPコンテンツ形式」レジストリ (セクション12.3) で定義されている数値のContent-Format識別子として指定されます。Acceptオプションが指定されていない場合、クライアントは優先順位を表明しません (したがって、デフォルト値は想定されません)。クライアントは、サーバーから返される表現が、示されたContent-Formatであることを好みます。可能であれば、サーバーは優先Content-Formatを返します。優先Content-Formatを返すことができない場合、別のエラーコードがこのレスポンスに優先しない限り、4.06 "Not Acceptable" をレスポンスとして送信しなければなりません (MUST)。

5.10.5. Max-Age​

Max-Ageオプションは、レスポンスが新鮮ではないと見なされる前にキャッシュできる最大時間を示します (セクション5.6.1を参照)。

オプション値は、0から2**32-1 (約136.1年) までの整数の秒数です。レスポンスにオプションがない場合、デフォルト値の60秒が想定されます。

値は、送信時に最新であることを意図しています。Max-Ageの値に厳しい許容範囲を持つリソースを提供するサーバーは、再送のたびに値を更新すべきです (SHOULD)。(セクション5.7.1も参照してください。)

5.10.6. ETag​

エンティティタグ (entity-tag) は、時間の経過とともに変化する同じリソースの表現を区別するためのリソースローカル識別子として使用することを目的としています。これは、リソースを提供するサーバーによって生成され、バージョン、チェックサム、ハッシュ、または時間など、さまざまな方法で生成できます。エンティティタグを受信するエンドポイントは、それを不透明なものとして扱い、その内容または構造についていかなる仮定も行ってはなりません (MUST)。(エンティティタグを生成するエンドポイントは、特に複数のETag値を保存したいクライアントや仲介者に関して、可能な限り最もコンパクトな表現を使用することが推奨されます。)

5.10.6.1. ETag as a Response Option (レスポンスオプションとしてのETag)​

レスポンス内のETagオプションは、「タグ付き表現 (tagged representation)」のエンティティタグの現在の値 (つまり、リクエストが処理された後) を提供します。Location-*オプションが存在しない場合、タグ付き表現はターゲットリソースの選択された表現 (セクション5.5.3) です。1つ以上のLocation-*オプションが存在し、したがって場所URIが示されている場合 (セクション5.10.7)、タグ付き表現は、場所URIへのGETリクエストによって取得される表現です。

ETagレスポンスオプションは、タグ付き表現がある任意のレスポンスに含めることができます (たとえば、4.04または4.00レスポンスでは意味がありません)。ETagオプションは、レスポンス内で2回以上発生してはなりません (MUST NOT)。

ETagオプションにはデフォルト値はありません。レスポンスに存在しない場合、サーバーはタグ付き表現のエンティティタグについて何も表明しません。

5.10.6.2. ETag as a Request Option (リクエストオプションとしてのETag)​

GETリクエストでは、以前にリソースから1つ以上の表現を取得し、これらを使用してETagレスポンスオプションを取得したエンドポイントは、これらの保存されたレスポンスの1つ以上に対してETagオプションのインスタンスを指定できます。

サーバーは、指定されたETagの1つが現在の表現のエンティティタグである場合、つまり有効である場合、2.05 Contentレスポンスの代わりに2.03 Validレスポンス (セクション5.9.1.3) を発行できます。2.03 Validレスポンスは、レスポンスオプションでこの特定のETagをエコーします。

事実上、クライアントは、保存された表現のいずれかが最新であるかどうか (セクション5.6.2を参照) を、再度転送する必要なしに判断できます。

ETagオプションは、リクエスト内で0回、1回、または複数回発生する場合があります (MAY)。

5.10.7. Location-Path and Location-Query​

Location-PathおよびLocation-Queryオプションは、絶対パス、クエリ文字列、またはその両方で構成される相対URIをまとめて示します。これらのオプションの組み合わせは、POSTリクエストの結果として作成されたリソースの場所を示すために、2.01 (Created) レスポンスに含まれます (セクション5.8.2を参照)。場所はリクエストURIに対して解決されます。

1つ以上のLocation-Pathおよび/またはLocation-Queryオプションを含むレスポンスが、これらのオプションを解釈するキャッシュを通過し、暗黙のURIが1つ以上の現在保存されているレスポンスを識別する場合、それらのエントリは新鮮ではないとしてマークされなければなりません (MUST)。

各Location-Pathオプションは、リソースへの絶対パスの1つのセグメントを指定し、各Location-Queryオプションは、リソースをパラメータ化する1つの引数を指定します。Location-PathおよびLocation-Queryオプションには、任意の文字シーケンスを含めることができます。パーセントエンコーディングは実行されません。Location-Pathオプションの値は "." または ".." であってはなりません (MUST NOT)。

オプションから場所URIを構築する手順は、最初の5つのステップがスキップされ、結果が相対URI参照になり、リクエストURIに対して解釈されることを除いて、セクション6.5と同様です。この方法で構築された相対URI参照には、常に絶対パスが含まれることに注意してください (たとえば、Location-Pathを省略してLocation-Queryを指定すると、URIのパスコンポーネントは "/" になります)。

相対URI参照を計算するために使用されるオプションは、まとめてLocation-*オプションと呼ばれます。Location-PathおよびLocation-Query以外に、将来さらにLocation-*オプションが定義される可能性があり、オプション番号128、132、136、および140が予約されています。Location-Pathおよび/またはLocation-Queryに加えて、これらの予約済みオプション番号のいずれかが発生し、サポートされていない場合は、4.02 (Bad Option) エラーが返されなければなりません (MUST)。

5.10.8. Conditional Request Options (条件付きリクエストオプション)​

条件付きリクエストオプションを使用すると、クライアントは、オプションで指定された特定の条件が満たされた場合にのみリクエストを実行するようにサーバーに要求できます。

これらの各オプションについて、指定された条件が満たされない場合、サーバーは要求されたメソッドを実行してはなりません (MUST NOT)。代わりに、サーバーは4.12 (Precondition Failed) Response Codeで応答しなければなりません (MUST)。

条件が満たされた場合、サーバーは、条件付きリクエストオプションが存在しないかのようにリクエストメソッドを実行します。

条件付きリクエストオプションがなければ、リクエストが2.xxまたは4.12 Response Code以外の結果になる場合、条件付きリクエストオプションは無視される場合があります (MAY)。

5.10.8.1. If-Match​

If-Matchオプションは、ターゲットリソースの1つ以上の表現のETagの現在の存在または値にリクエストを条件付けるために使用される場合があります (MAY)。If-Matchは通常、複数のクライアントが同じリソースに対して並行して動作しているときに誤って上書きされること (つまり、「更新の喪失」問題) を防ぐ手段として、PUTリクエストなどのリソース更新リクエストに役立ちます。

If-Matchオプションの値は、ETagまたは空の文字列です。ETagを持つIf-Matchオプションは、その正確なETagを持つ表現と一致します。空の値を持つIf-Matchオプションは、既存の任意の表現と一致します (つまり、ターゲットリソースの現在の表現の存在に前提条件を置きます)。

If-Matchオプションは複数回発生する可能性があります。いずれかのオプションが一致する場合、条件は満たされます。

1つ以上のIf-Matchオプションがあるが、どのオプションも一致しない場合、条件は満たされません。

5.10.8.2. If-None-Match​

If-None-Matchオプションは、ターゲットリソースが存在しないことにリクエストを条件付けるために使用される場合があります (MAY)。If-None-Matchは、複数のクライアントが同じリソースに対して並行して動作しているときに誤って上書きされることを防ぐ手段として、PUTリクエストなどのリソース作成リクエストに役立ちます。If-None-Matchオプションは値を持ちません。

ターゲットリソースが存在する場合、条件は満たされません。

(条件が決して満たされないため、1つのリクエストでIf-MatchとIf-None-Matchオプションを組み合わせることはあまり役に立ちません。)

5.10.9. Size1 Option​

Size1オプションは、リクエスト内のリソース表現に関するサイズ情報を提供します。オプション値は整数のバイト数です。その主な用途は、ブロック単位の転送 [BLOCK] です。本仕様では、サーバーが処理できる最大リクエストエンティティサイズを示すために、4.13レスポンス (セクション5.9.2.9) で使用されます。