表現

RESTful Web サービスでは、ビューのデータを以下の 3 つの形式で表現できます。

RESTful Web サービスでは、デフォルトで HTML 表現によるデータが返されます。ただし、HTTP リクエストで適切な Accept ヘッダーを送信するか、Web サービスを呼び出す URL で $format パラメーターを指定することによって、別の表現 (XML または JSON) を選択できます ($format パラメーターで指定できる値については、「 RESTful Web サービスの入力パラメーター 」の表「 Denodo RESTful Web サービスおよび公開されている REST Web サービスでサポートされているパラメーター 」を参照)。

RESTful Web サービスでは、リクエストに HTTP ヘッダー Accept がなく、URL でパラメーター $format を指定していない場合は、デフォルトの表現 (HTML) が返されます。また、 Accept ヘッダーでいくつかのメディアタイプを指定していて、その中に text/html または application/xhtml+xml があると HTML 表現が返されます。ただし、 Accept ヘッダーで text/html または application/xhtml+xml の品質係数が 1 未満である場合は、最も大きい品質係数 (以下の例を参照) の表現が返されます。

以下の表に、リクエストの HTTP ヘッダー Accept の値に応じた RESTful Web サービスの出力を示します。

Accept HTTP ヘッダーに応じて RESTful Web サービスから返される表現

リクエストの Accept HTTP ヘッダー

出力表現

text/html

HTML

application/xhtml+xml

HTML

application/xml

XML

application/json

JSON

application/json、application/xml、text/html

HTML

リストの先頭のメディアタイプではありませんが、デフォルト表現であるため。

application/xhtml+xml;q=0.9,applicat ion/json

JSON

デフォルト表現 (HTML) の品質係数が、サポートされている他の表現の品質係数より小さいため。

application/json;q=0.2,application/x ml;q=0.1

JSON

デフォルト表現 (XML) の品質係数が、サポートされている他の表現の品質係数より小さいため。

application/rss+xml

このメディアタイプは、適切に構成した REST Web サービスでのみサポートされているので、RESTful Web サービスでは HTTP エラー 406 (Not Acceptable) が返されます。

$format パラメーターの値は HTTP ヘッダー Accept の値より優先されます。たとえば、リクエストにパラメーター $format=json を設定し、HTTP ヘッダー Accept の値を text/html としている場合はデータの JSON 表現が返されます。

XML 表現

クライアントで XML 表現を選択した場合、RESTful Web サービスでは XML ドキュメントが返されます。

この表現を選択するには、HTTP リクエストに Accept ヘッダー application/xml を追加するか、URL に $format=XML パラメーターを追加する (たとえば、 http://localhost:9090/denodo-restfulws/admin/views/customer?$format=XML) 必要があります。

XML 表現に関する一般的な注意点を以下に示します。

  • リンクの表現には、ATOM 仕様 (Atom Syndication Format) の link エレメントを利用します。

  • リンクの rel 属性の値 self には、IANA (http://www.iana.org/assignments/link-relations/link-relations.xml) で定義されている標準の意味があります。つまり、このリンクは親エレメントの ID を指定します。

  • prevnext には、IANA で定義されている標準の意味があります。つまり、それぞれ前または次の 1 ページにアクセスするために使用します。

  • 特定のリンクで表現されている関係を示す標準的な ID が存在しない場合は、Denodo で定義されている URI を使用してその関係のセマンティクスを指定します。

    たとえば、値 http://www.denodo.com/restful/rels/viewSchema は、特定のビューのスキーマにアクセスできるリンクを示します。

データベースの XML 表現

以下 の図に、 support データベースの XML 表現の例を示します。

このドキュメントを取得するための URL は以下のようになります。

http://localhost:9090/denodo-restfulws/support?$format=XML

データベースのビューごとに view-metadata エレメントが存在します。このエレメントには、以下の情報が記述されています。

  • view-metadata エレメント自体を取得するためのリンク。

  • ビューのスキーマにアクセスするためのリンク。XML スキーマで記述されています。

  • ビューの内容を取得するためのリンク。

  • ビューのアソシエーションを取得するためのリンク。

データベースの XML 表現
<?xml version="1.0" encoding="UTF-8"?>
<db name="support" xmlns="http://www.denodo.com/restful" xmlns:atom="http://www.w3.org/2005/Atom">
    <description>Customers support database</description>
    <view-metadata name="customer">
        <description>Acme customers</description>
        <atom:link rel="self"
            href="http://localhost:9090/denodo-restfulws/support/views/customer/$metadata" />
        <atom:link rel="http://www.denodo.com/restful/rels/viewSchema"
            title="View Schema"
            href="views/customer/$schema" />
        <atom:link
            rel="http://www.denodo.com/restful/rels/viewElements"
            title="View Elements" href="views/customer"/>
        <atom:link
            rel="http://www.denodo.com/restful/rels/viewAssociations"
            title="View Associations"
            href="views/customer/$associations "/>
    </view-metadata>
    <view-metadata name="order">
        <description>Acme's orders database</description>
        <atom:link rel="self"
            href="http://localhost:9090/denodo-restfulws/support/views/order/$metadata" />
        <atom:link
            rel="http://www.denodo.com/restful/rels/viewSchema"
            title="View Schema"
            href="views/order/$schema" />
        <atom:link
            rel="http://www.denodo.com/restful/rels/viewElements"
            title="View Elements"
            href="views/order" />
        <atom:link
            rel="http://www.denodo.com/restful/rels/viewAssociations"
            title="View Associations"
            href="views/order/$associations "/>
    </view-metadata>
    <view-metadata name="orderline"><atom:link rel="self"
            href="http://localhost:9090/denodo-restfulws/support"/>
</db>

ビューの XML 表現

以下 の図に、 support データベースの customer ビューの XML 表現の例を示します。

このドキュメントを取得するための URL は以下のようになります。

http://localhost:9090/denodo-restfulws/support/views/customer?$format=XML

この表現には、ビューの名前と説明およびビューの各行の customer エレメントが記述されています。

各エレメントには、ビューの各アソシエーションを表すリンクが記述されています。このリンクで、そのエレメントのアソシエーションをたどります (「 XML representation of a view 」では、特定の顧客の注文が返されます)。

デフォルトでは、ビューのすべての属性が返されます。出力をカスタマイズする手順については、「 RESTful Web サービスの入力パラメーター 」を参照してください。

この表現では、 prev リンクと next リンクを使用した改ページがサポートされています。これらのリンクは、URL に $start_index$count の両方または一方を追加した場合にのみ表示されます。

ビューの XML 表現のサンプル
<?xml version="1.0" encoding="UTF-8"?>
    <denodo:view name="customer"
            xmlns="http://www.denodo.com/support/views/customer"
            xmlns:denodo="http://www.denodo.com/restful"
            xmlns:atom="http://www.w3.org/2005/Atom"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <description>Acme customers</description>
      <customer>
          <cid>1</cid>
          <cname>RoadRunner</cname>
          <c_address>Monument Valley</c_address>
          <c_description>He is fast</c_description>
          <atom:link rel="self"
                href="http://localhost:9090/denodo-restfulws/support/views/customer/1?$format=XML"/>
          <atom:link
                rel="http://localhost:9090/denodo-restfulws/support/views/customer/supportcases"
                title="Support cases of this customer"
                href="../supportcase?$filter=scid&3D1&$format=XML" />
           <atom:link
                 rel="http://localhost:9090/denodo-restfulws/support/views/customer/orders"
                 title="Orders of this customer"
                 href="../order?$filter=oid&3D1&format=XML" />
       </customer>

       <customer></customer><atom:link rel="self"
             href="http://localhost:9090/denodo-restfulws/support/views/customer?$format=XML"/>
       <atom:link rel="prev" title="Previous"
             href="?$count=10&$start_index=0">
       <atom:link rel="next" title="Next"
             href="?$count=10&$start_index=20">
</denodo:view>

警告

ビューの名前またはそのいずれかのフィールドの名前に、XML エレメントの名前では無効な文字 (「+」、「*」、空白文字など) を使用していると、RESTful Web サービスでは HTTP コード 406 (Not acceptable) が返されます。HTML 表現と JSON 表現は、この制限の影響を受けません。

ビューを REST Web サービスとして公開する場合は、Virtual DataPort によって、フィールドの名前から無効な文字が自動的に削除されます。


ビューの表現をリクエストした場合は、blob フィールドの値が返されません。ビューにプライマリキーが存在する場合、結果には blob 値へのリンクが記述されます。以下に例を示します。

blob 値が NULL の場合、そのフィールドは nil 属性が true に設定された空のエレメントとして表されます (<image xsi:nil="true"/> など)。

ビューにプライマリキーが存在しない場合、blob フィールドは空のエレメントとして表されます。その xsi:nil 属性は、blob 値が NULL であれば true 、それ以外であれば false に設定されます。

「ビューエレメント」リソースの XML 表現

以下 の図に、 customer ビューの行の XML 表現の例を示します。この行は、そのプライマリキーで特定されています。

このドキュメントを取得する URL は http://localhost:9090/denodo-restfulws/support/views/customer/1?$format=XML です。

この URL で 1 は、 customer ビューの行に設定されたプライマリキーの値です。

ビューに blob 型のフィールドが 1 つまたは複数存在する場合、次のようなマルチパートメッセージの応答 (HTTP ヘッダー Content-type: multipart/mixed がある応答) が返されます。

  • このメッセージの先頭のパートは、データを記述した XML ドキュメントです。

  • 以降のパートには、 base64 でエンコードされた各 blob フィールドの値が記述されています。

メッセージの各パートには独自の Content-type ヘッダーがあります。blob フィールドのコンテンツタイプを設定している場合 (「 基本ビューの Blob フィールドの扱い 」を参照)、そのパートの HTTP ヘッダーの値が、コンテンツタイプの定数またはその式の評価結果に設定されます。blob フィールドのコンテンツタイプを設定していない場合、 Content-typeapplication/octet-stream になります。

注釈

ビューにプライマリキーが存在する場合、アソシエーションをたどって blob 値を取得するためのリンクのみが返されます。

エレメントの XML 表現
<?xml version="1.0" encoding="UTF-8"?>
<customer xmlns="http://www.denodo.com/restful/support/views/customer"
          xmlns:atom="http://www.w3.org/2005/Atom"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <cid>1</cid>
    <cname>RoadRunner</cname>
    <c_address>Monument Valley</c_address>
    <c_description>He is fast</c_description>
    <atom:link rel="self"
          href="http://localhost:9090/denodo-restfulws/support/views/customer/1"/>
    <atom:link rel="http://localhost:9090/denodo-restfulws/support/views/customer/supportcases"
          title="Support cases of this customer"
          href="../supportcase?$filter=sid%3D1"/>
    <atom:link rel="http://localhost:9090/denodo-restfulws/support/views/customer/orders"
          title="Orders of this customer"
          href="../order?$filter=oid%3D1"/>
</customer>

アソシエーションの XML 表現

アソシエーションのメタデータは、アソシエーションとその 2 つのエンドポイントに関する情報を提供します。

以下 の図に、 customer_order アソシエーションの XML 表現の例を示します。

このドキュメントを取得する URL を以下に示します。

http://localhost:9090/denodo-restfulws/support/ associations/customer_order/$metadata?$format=XML

アソシエーションの XML 表現のサンプル
<association-metadata referential-constraint="false" name="customer_order">
    <description>Association of customers and orders</description>
    <endpoint
        principal="false"
        multiplicity="1"
        role-description="Orders of this customer"
        role-name="orders"
        view-name="CUSTOMER"/>
    <endpoint
        principal="false"
        multiplicity="0,*"
        role-description="Customer of this order"
        role-name="customer"
        view-name="ORDER"/>
    <ns2:link
        href="associations/customer_order/$metadata"
        rel="self"/>
</association-metadata>

JSON 表現

クライアントで JSON 表現を選択した場合、リクエストしたエレメント (データベース、ビュー、またはビューの行) が記述された JSON ドキュメント (JavaScript Object Notation) が RESTful Web サービスから返されます。

この表現を選択するには、HTTP リクエストに Accept ヘッダー application/json を追加するか、URL に $format=JSON パラメーターを追加する必要があります。

JSON 表現は XML 表現と同様です。

ビューの JSON 表現のサンプル
{
  "name": "customer",
  "description": "Acme Customers",
  "elements" : [
    {
      "cid": 1234,
      "cname": "Roadrunner",
      "address": "Monument Valley",
      "description": "He is fast",
      "links" : [
        {
          "rel": "self",
          "href": "http://localhost:9090/denodo-restfulws/ support/views/customer/1234"
        },
        {
          "rel":"http://localhost:9090/denodo-restfulws/support/views/customer/supportcases",
          "title":"Support cases of this customer",
          "href":"../supportcase?$filter=customer_id%3D1234"},
        {
          "rel": "http://localhost:9090/denodo-restfulws/support/views/customer/orders",
          "title": "Orders of this customer",
          "href": "../order=$filter=customer_id%3D1234"
         }
      ]
    },
    {
      "cid": 5678,
      "cname": "Wile E. Coyote",
      "address": "Flagstaff, Arizona",
      "description": "He is fast",
      "links" : [
        {
          "rel": "self",
          "href": "http://localhost:9090/denodo-restfulws/ support/views/customer/5678"
        },
        {
          "rel":"http://localhost:9090/denodo-restfulws/support/views/customer/supportcases",
          "title":"Support cases of this customer",
          "href":"../supportcase?$filter=customer_id%5678"},
        {
          "rel": "http://localhost:9090/denodo-restfulws/support/views/customer/orders",
          "title": "Orders of this customer",
          "href": "../order=$filter=customer_id%5678"
         }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "http://localhost:9090/denodo-restfulws/support/views/customers"
    },
    {
      "rel": "prev",
      "title": "Previous",
      "href": "?$count=2&$start_index=0"
    },
    {
      "rel": "next",
      "title": "Next",
      "href": "?$count=2&$start_index=3"
    }
  ]

ビューの表現をリクエストした場合 (ビューの行のプライマリキーを URL で指定していない場合) は、blob フィールドの値が返されません。ビューにプライマリキーが存在する場合、結果には blob 値へのリンクが記述されます。以下に例を示します。

blob 値が NULL の場合、そのフィールドは NULL 値 ("image": null など) として表されます。

ビューにプライマリキーが存在しない場合、blob フィールドは、blob の値が NULL であれば空文字列 ("image": "")、それ以外であれば NULL ("image": null) として表されます。


URL が「ビューエレメント」 (ビューのプライマリキーで特定した行) を表し、ビューに blob 型のフィールドが存在する場合、次のようなマルチパートメッセージの応答 (HTTP ヘッダー Content-type: multipart/mixed がある応答) が返されます。

  • このメッセージの先頭のパートは、データを記述した JSON ドキュメントです。

  • 以降のパートには、 base64 でエンコードされた各 blob フィールドの値が記述されています。

メッセージの各パートには独自の Content-type ヘッダーがあります。blob フィールドのコンテンツタイプを設定している場合 (「 基本ビューの Blob フィールドの扱い 」を参照)、そのパートの HTTP ヘッダーの値が、コンテンツタイプの定数またはその式の評価結果に設定されます。blob フィールドのコンテンツタイプを設定していない場合、 Content-typeapplication/octet-stream になります。

注釈

ビューにプライマリキーが存在する場合、アソシエーションをたどって blob 値を取得するためのリンクのみが返されます。

HTML 表現

HTML 表現はデフォルトの表現であり、人間による利用を目的としています。

以下の条件のいずれかが満たされる場合に RESTful Web サービスから HTML 表現が返されます。

  • application/xhtml+xml または text/html を値とする Accept ヘッダーが HTTP リクエストに追加されている。

  • Accept ヘッダーが HTTP リクエストに追加されていない。

  • $format パラメーターが URL に追加されていない。

HTML representation of a view

ビューの HTML 表現

HTML 表現は、以下に示す点で、XML 表現および JSON 表現と異なります。

  • ビューエレメントのフィルター処理、応答に追加するフィールドの選択、および結果の並べ替えのためのクエリフォームがビューごとに存在します (「 HTML query form 」を参照)。

    このフォームにアクセスするには、ビューの表現で [Search] をクリックします。

    このフォームに用意されている機能は、呼び出し URL に特定のパラメーターを追加することによって、XML 表現および JSON 表現でも使用できます (「 RESTful Web サービスの入力パラメーター 」を参照)。

  • ビューのアソシエーションごとに、ビューの複数のアソシエーション間での移動を容易にするリンクがあります。このビューに関連付けられているビューは [Related Views] ボックスに一覧表示されます。

  • [Total number of rows...] の横にある [get] をクリックすると、結果セットにある行の総数が得られます。この数は、表示されている行数より多いこともあります。HTML 表現ではページ構成としたデータが表示されるからです。

    たとえば、customer ビューのデータを表示する場合、デフォルトの HTML 表現では 25 行のみが表示されます。しかし、このリンクをクリックすると、customer ビューにあるすべての行の数が表示されます。以下のクエリが実行されて、その数が取得されるからです。

    SELECT_NAVIGATIONAL COUNT(*)
    FROM view
    WHERE 
    

    この行数の取得では、URL に設定した条件が考慮されます。

  • ビューに blob 型のフィールド および プライマリキーが存在する場合、その blob 値は、フィールド名をラベルとするリンクで表現されます。このリンクをクリックすると、該当の Content-Type HTTP ヘッダーと共にフィールドの値が返されます。

    フィールドのコンテンツタイプを設定している場合 (「 基本ビューの Blob フィールドの扱い 」を参照)、そのパートの HTTP ヘッダー Content-Type の値が、コンテンツタイプの定数またはその式の評価結果に設定されます。コンテンツタイプを設定していない場合は、RESTful Web サービスによってコンテンツタイプが推定されます。

    ビューにプライマリキーが存在しない場合、blob フィールドは非表示になり、その値をリクエストすることはできません。

  • 別の資格情報でサービスの使用を開始するには [Logout] リンクをクリックします。

    RESTful Web サービスではセッションが維持されませんが、通常は、最初に入力した有効な資格情報が、各リクエストと共にブラウザから自動的に送信されます。[Logout] をクリックすると、新しい資格情報の入力が必要であることが RESTful Web サービスからブラウザに通知されます。

    他の表現 (JSON および XML) にはこのオプションがありません。別の資格情報を使用して接続する場合は、RESTful Web サービスに送信するリクエストの認証ヘッダーを変更すれば済むからです。

注釈

ビューにプライマリキーが存在する場合、アソシエーションをたどって blob 値を取得するためのリンクのみが返されます。

HTML query form

HTML クエリフォーム