CData API Serverで作成したAPIでパラメータを使ってみる

2020.06.30

はじめに

データアナリティクス事業本部のkobayashiです。

REST API構築ツール CData API Server で作成したAPIにはGETリクエスト使う際に以下の内容をパラメータで簡単に制御できます。

  • プロパティの選択($select)
  • リソースのフィルタリング($filter)
  • フルテキスト検索機能($search)
  • リソースのソート($orderby)
  • 取得するリソースの数($top)
  • スキップするアイテムの数($skip)

これらのパラメータは単独で使う事もできますし&で繋げて複数を組み合わせて使うこともできます。

今回はこれらパラメータを使ってAPIにGETリクエストを送りそのレスポンスを確認してみたいと思います。

CData API Serverのインストール方法やデータソースの設定方法は下記のエントリをご参照ください。

環境

  • Windows 10
  • CData API Server - 19.0.7362.0
  • データソース
    • MariaDB 10.5

また今回使用しているCData API Serverのホストとポートは以下になります。

192.168.7.129:8153

パラメータ未指定の場合のレスポンス確認

まずはパラメータが未指定の場合のレスポンスを確認してみます。

http://192.168.7.129:8153/api.rsc/world_country/

このURLでのレスポンスは以下になります。

{
  "@odata.context": "http://192.168.7.129:8153/api.rsc/$metadata#world_country",
  "value": [
    {
      "Code": "ABW",
      "Capital": 129,
      "Code2": "AW",
      "Continent": "North America",
      "GNP": 828.00,
      "GNPOld": 793.00,
      "GovernmentForm": "Nonmetropolitan Territory of The Netherlands",
      "HeadOfState": "Beatrix",
      "LifeExpectancy": 78.4,
      "LocalName": "Aruba",
      "Name": "Aruba",
      "Population": 103000,
      "Region": "Caribbean",
      "SurfaceArea": 193.00,
      "IndepYear": null
    },
    {
      "Code": "AFG",
      "Capital": 1,
      "Code2": "AF",
      "Continent": "Asia",
      "GNP": 5976.00,
      "GovernmentForm": "Islamic Emirate",
      "HeadOfState": "Mohammad Omar",
      "IndepYear": 1919,
      "LifeExpectancy": 45.9,
      "LocalName": "Afganistan/Afqanestan",
      "Name": "Afghanistan",
      "Population": 22720000,
      "Region": "Southern and Central Asia",
      "SurfaceArea": 652090.00,
      "GNPOld": null
    },
    {
      "Code": "AGO",
      "Capital": 56,
      "Code2": "AO",
      "Continent": "Africa",
      "GNP": 6648.00,
      "GNPOld": 7984.00,
      "GovernmentForm": "Republic",
      "HeadOfState": "José Eduardo dos Santos",
      "IndepYear": 1975,
      "LifeExpectancy": 38.3,
      "LocalName": "Angola",
      "Name": "Angola",
      "Population": 12878000,
      "Region": "Central Africa",
      "SurfaceArea": 1246700.00
    },
 ...
  ]
}

以降の確認はこのURLをベースにして確認していきます。

プロパティの選択($select)

取得するプロパティを指定するには$selectを使用します。 $select=の後に取得したいプロパティを指定すればよく、複数の場合はカンマ区切りでプロパティをつなげればプロパティを絞り込んだレスポンスが返ってきます。

URL

Code,GovernmentForm,LocalName,Region,SurfaceArea,Populationのプロパティを取得

http://192.168.7.129:8153/api.rsc/world_country/?$select=Code,GovernmentForm,LocalName,Region,SurfaceArea,Population

レスポンス

指定したプロパティのみがレスポンスに含まれています。

{
  "@odata.context": "http://192.168.7.129:8153/api.rsc/$metadata#world_country",
  "value": [
    {
      "Code": "ABW",
      "GovernmentForm": "Nonmetropolitan Territory of The Netherlands",
      "LocalName": "Aruba",
      "Region": "Caribbean",
      "SurfaceArea": 193.00,
      "Population": 103000
    },
    {
      "Code": "AFG",
      "GovernmentForm": "Islamic Emirate",
      "LocalName": "Afganistan/Afqanestan",
      "Region": "Southern and Central Asia",
      "SurfaceArea": 652090.00,
      "Population": 22720000
    },
    {
      "Code": "AGO",
      "GovernmentForm": "Republic",
      "LocalName": "Angola",
      "Region": "Central Africa",
      "SurfaceArea": 1246700.00,
      "Population": 12878000
    }
...
  ]
}

リソースのフィルタリング($filter)

取得するリソースをフィルタするには$filterを使用します。 $filter=の後に取得したい条件を指定することでフィルタリングされたレスポンスが返ってきます。 フィルタするには以下の演算子と関数が使えます。

演算子 意味
Eq 等しい
Ne 等しくない
Gt 大きい
Ge 以上
Lt 小さい
Le 以下
Not 式の結果を反転
関数 意味
startswith(プロパティ,文字列) プロパティが文字列で始まっている
endswith(プロパティ,文字列) プロパティが文字列で終わっている
contains(プロパティ,文字列) プロパティが文字列を含んでいる
toupper(プロパティ) プロパティを大文字にする
tolower(プロパティ) プロパティを小文字にする

フィルタ条件は複数使うこともでき、andorでフィルタ条件を複数組み合わせる事もできます。

URL

Population10,000,000以上でContinentAsiaNamepaを含んでいるリソースを取得

http://192.168.7.129:8153/api.rsc/world_country/?$filter=Population Gt 10000000 and Continent Eq 'Asia' and contains(Name,'pa')

レスポンス

指定したフィルタに合致したレスポンスとなっています。

{
  "@odata.context": "http://192.168.7.129:8153/api.rsc/$metadata#world_country",
  "value": [
    {
      "Code": "JPN",
      "Capital": 1532,
      "Code2": "JP",
      "Continent": "Asia",
      "GNP": 3787042.00,
      "GNPOld": 4192638.00,
      "GovernmentForm": "Constitutional Monarchy",
      "HeadOfState": "Akihito",
      "IndepYear": -660,
      "LifeExpectancy": 80.7,
      "LocalName": "Nihon/Nippon",
      "Name": "Japan",
      "Population": 126714000,
      "Region": "Eastern Asia",
      "SurfaceArea": 377829.00
    },
    {
      "Code": "NPL",
      "Capital": 2729,
      "Code2": "NP",
      "Continent": "Asia",
      "GNP": 4768.00,
      "GNPOld": 4837.00,
      "GovernmentForm": "Constitutional Monarchy",
      "HeadOfState": "Gyanendra Bir Bikram",
      "IndepYear": 1769,
      "LifeExpectancy": 57.8,
      "LocalName": "Nepal",
      "Name": "Nepal",
      "Population": 23930000,
      "Region": "Southern and Central Asia",
      "SurfaceArea": 147181.00
    },
    {
      "Code": "PAK",
      "Capital": 2831,
      "Code2": "PK",
      "Continent": "Asia",
      "GNP": 61289.00,
      "GNPOld": 58549.00,
      "GovernmentForm": "Republic",
      "HeadOfState": "Mohammad Rafiq Tarar",
      "IndepYear": 1947,
      "LifeExpectancy": 61.1,
      "LocalName": "Pakistan",
      "Name": "Pakistan",
      "Population": 156483000,
      "Region": "Southern and Central Asia",
      "SurfaceArea": 796095.00
    }
...
  ]
}

データソースがMySQL、SQL Server、MongoDBについては$serachでフルテキスト検索機能が使えます。 $search=の後に文字列を指定することで全プロパティでその文字列を含むリソースに絞り込みます。

URL

全プロパティの中でrateを一つでも含んでいるリソースを取得

http://192.168.7.129:8153/api.rsc/world_country/?$search=rate

レスポンス

いずれかのプロパティにrateを含んでいるレスポンスとなっています。

{
  "@odata.context": "http://192.168.7.129:8153/api.rsc/$metadata#world_country",
  "value": [
    {
      "Code": "AFG",
      "Capital": 1,
      "Code2": "AF",
      "Continent": "Asia",
      "GNP": 5976.00,
      "GovernmentForm": "Islamic Emirate",
      "HeadOfState": "Mohammad Omar",
      "IndepYear": 1919,
      "LifeExpectancy": 45.9,
      "LocalName": "Afganistan/Afqanestan",
      "Name": "Afghanistan",
      "Population": 22720000,
      "Region": "Southern and Central Asia",
      "SurfaceArea": 652090.00,
      "GNPOld": null
    },
    {
      "Code": "ARE",
      "Capital": 65,
      "Code2": "AE",
      "Continent": "Asia",
      "GNP": 37966.00,
      "GNPOld": 36846.00,
      "GovernmentForm": "Emirate Federation",
      "HeadOfState": "Zayid bin Sultan al-Nahayan",
      "IndepYear": 1971,
      "LifeExpectancy": 74.1,
      "LocalName": "Al-Imarat al-´Arabiya al-Muttahida",
      "Name": "United Arab Emirates",
      "Population": 2441000,
      "Region": "Middle East",
      "SurfaceArea": 83600.00
    },
    {
      "Code": "ATA",
      "Code2": "AQ",
      "Continent": "Antarctica",
      "GNP": 0.00,
      "GovernmentForm": "Co-administrated",
      "HeadOfState": "",
      "LocalName": "–",
      "Name": "Antarctica",
      "Population": 0,
      "Region": "Antarctica",
      "SurfaceArea": 13120000.00,
      "LifeExpectancy": null,
      "IndepYear": null,
      "GNPOld": null,
      "Capital": null
    },
...
  ]
}

リソースのソート($orderby)

リソースをソートした状態で取得するには$orderbyを使用します。 $orderby=の後にソートしたいプロパティを指定すればよく、複数の場合はカンマ区切りでプロパティをつなげればプロパティをソートした状態のレスポンスが返ってきます。 またデフォルトでは昇順になっているので降順にする場合はプロパティ descのようにすれば降順になります。

URL

Continentは昇順、Nameは降順で並べ替え

http://192.168.7.129:8153/api.rsc/world_country/?$orderby=Continent,Name desc

レスポンス

リソースがソートされたレスポンスとなっています。

{
  "@odata.context": "http://192.168.7.129:8153/api.rsc/$metadata#world_country",
  "value": [
    {
      "Code": "YEM",
      "Capital": 1780,
      "Code2": "YE",
      "Continent": "Asia",
      "GNP": 6041.00,
      "GNPOld": 5729.00,
      "GovernmentForm": "Republic",
      "HeadOfState": "Ali Abdallah Salih",
      "IndepYear": 1918,
      "LifeExpectancy": 59.8,
      "LocalName": "Al-Yaman",
      "Name": "Yemen",
      "Population": 18112000,
      "Region": "Middle East",
      "SurfaceArea": 527968.00
    },
    {
      "Code": "VNM",
      "Capital": 3770,
      "Code2": "VN",
      "Continent": "Asia",
      "GNP": 21929.00,
      "GNPOld": 22834.00,
      "GovernmentForm": "Socialistic Republic",
      "HeadOfState": "Trân Duc Luong",
      "IndepYear": 1945,
      "LifeExpectancy": 69.3,
      "LocalName": "Viêt Nam",
      "Name": "Vietnam",
      "Population": 79832000,
      "Region": "Southeast Asia",
      "SurfaceArea": 331689.00
    },
    {
      "Code": "UZB",
      "Capital": 3503,
      "Code2": "UZ",
      "Continent": "Asia",
      "GNP": 14194.00,
      "GNPOld": 21300.00,
      "GovernmentForm": "Republic",
      "HeadOfState": "Islam Karimov",
      "IndepYear": 1991,
      "LifeExpectancy": 63.7,
      "LocalName": "Uzbekiston",
      "Name": "Uzbekistan",
      "Population": 24318000,
      "Region": "Southern and Central Asia",
      "SurfaceArea": 447400.00
    }
...
  ]
}

取得するリソースの数($top)とスキップするアイテムの数($skip)

$topは取得するリソースの件数を指定するパラメータ、$skipはスキップする件数を指定するパラメータになります。

この2つのパラメータは組み合わせて使用することが多いのでまとめて確認してみます。この手法は主にページネーションを行う場合に使うことが多いと思います。

URL

1.最初の5件を取得

http://192.168.7.129:8153/api.rsc/world_country/?$select=Code,LocalName,Population&$top=5

2.次のの5件を取得

http://192.168.7.129:8153/api.rsc/world_country/?$select=Code,LocalName,Population&$top=5&$skip=5

レスポンス

1.最初の5件のレスポンス

{
  "@odata.context": "http://192.168.7.129:8153/api.rsc/$metadata#world_country",
  "value": [
    {
      "Code": "ABW",
      "LocalName": "Aruba",
      "Population": 103000
    },
    {
      "Code": "AFG",
      "LocalName": "Afganistan/Afqanestan",
      "Population": 22720000
    },
    {
      "Code": "AGO",
      "LocalName": "Angola",
      "Population": 12878000
    },
    {
      "Code": "AIA",
      "LocalName": "Anguilla",
      "Population": 8000
    },
    {
      "Code": "ALB",
      "LocalName": "Shqipëria",
      "Population": 3401200
    }
  ]
}

2.次の5件のレスポンス

{
  "@odata.context": "http://192.168.7.129:8153/api.rsc/$metadata#world_country",
  "value": [
    {
      "Code": "AND",
      "LocalName": "Andorra",
      "Population": 78000
    },
    {
      "Code": "ANT",
      "LocalName": "Nederlandse Antillen",
      "Population": 217000
    },
    {
      "Code": "ARE",
      "LocalName": "Al-Imarat al-´Arabiya al-Muttahida",
      "Population": 2441000
    },
    {
      "Code": "ARG",
      "LocalName": "Argentina",
      "Population": 37032000
    },
    {
      "Code": "ARM",
      "LocalName": "Hajastan",
      "Population": 3520000
    }
  ]
}

まとめ

CData API ServerにGETリクエストを投げる際に様々なパラメータを指定してそのレスポンスを確認しました。 次回は集計処理を試してみたいと思います。

最後まで読んで頂いてありがとうございました。