この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
はじめに
データアナリティクス事業本部の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(プロパティ) | プロパティを小文字にする |
フィルタ条件は複数使うこともでき、and
とor
でフィルタ条件を複数組み合わせる事もできます。
URL
Population
が10,000,000
以上でContinent
がAsia
でName
にpa
を含んでいるリソースを取得
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
}
...
]
}
フルテキスト検索機能($search)
データソースが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リクエストを投げる際に様々なパラメータを指定してそのレスポンスを確認しました。 次回は集計処理を試してみたいと思います。
最後まで読んで頂いてありがとうございました。