DBAPI/食品検索の変更点

追加された行はこの色です。
削除された行はこの色です。
DBAPI/食品検索へ行く。
#author("2022-08-29T09:06:45+09:00","","")
[[FrontPage]]

&size(24){DBAPI/バッチ検索};

* API情報 [#q6190828]

|~名称|食品検索|
|~APIバージョン|2|
|~認証タイプ|なし|
|~URL|&#104;&#116;&#116;&#112;&#115;&#58;&#47;&#47;&#40;&#65;&#80;&#73;&#12469;&#12540;&#12496;&#12540;&#21517;&#41;/services/api2/(アクセスコード)/dbbatch/(コマンド)/|
|~Method|POST|
|~リクエストボディ形式|JSON|
|~データ更新頻度目安|毎日|

* 概要 [#jfe13a2c]

条件を指定して、バッチ処理により食品を検索する。
カスタム食品検索より実行時間がかかるが、自由な条件で食品を検索できる。返却数も設定により無制限にできる。


* アクセス手順 [#ya59d11f]

使用は以下の手順を実行する。

- (手順1:query) クライアントは、JSON形式でクエリーを作成してリクエストボディにセットし、URLに対してPOSTで送信する。
- (手順2:status) バッチIDが返却され、サーバー側ではバッチ処理が開始される。クライアントはバッチIDを使用して処理の完了をpollingする。
- (手順3:getinfo) 完了したバッチ処理に対して、結果データセットの情報を要求する。
- (手順4:getdata) データセット情報に基づき、結果データを取得する

トークン使用回数制限が設定されている場合、手順queryでは使用回数が加算される。&br;
それ以外の手順は、使用回数は加算されない。


** 手順 query [#l9016c71]

検索に必要なクエリーをjsonで記述し、リクエストボディにセットしてURLにPOSTで送信する。
|~コマンド|query|
|~URL|&#104;&#116;&#116;&#112;&#115;&#58;&#47;&#47;&#40;&#65;&#80;&#73;&#12469;&#12540;&#12496;&#12540;&#21517;&#41;/services/api2/(アクセスコード)/dbbatch/query/|
|~トークン使用回数カウント|あり|


*** クエリーのプロパティ一覧 [#h0a9b879]
|区分|パラメータ名|内容|形式または許容値|説明・省略可否など|h
|定数|ver|パラメーターオブジェクトのバージョン|数値|必須・1固定|
|定数|type|パラメーターオブジェクトのタイプ|数値|必須・query固定|
|フィルター|inword|検索テキスト|文字列|テキスト検索語|
|フィルター|incond|検索テキストの条件|許容値 and/or|テキスト検索語が複数の場合の条件|
|フィルター|matching|テキスト検索タイプ|許容値 boolean/naturallang/naturallqe|boolean=ブール全文検索/naturallang=自然言語全文検索/naturallqe=クエリー拡張全文検索|
|フィルター|exword|除外テキスト|文字列|ブール全文検索での除外語|
|フィルター|filtersn|メーカー名フィルタ|文字列|指定されたメーカー名のみ抽出|
|フィルター|filtersn_match|メーカー名フィルタの条件|許容値 and/or|メーカー名フィルタが複数の場合の条件|
|フィルター|flagsn|メーカー名付きフラグ|許容値 yes/no|yes=メーカー名付きのみ/no=メーカー名なしのみ|
|フィルター|exelement|除外構成要素|食品オブジェクトID|指定された食品オブジェクトIDを構成要素に持つ食品を除外|
|フィルター|inelement|絞込構成要素|食品オブジェクトID|指定された食品オブジェクトIDを構成要素に持つ食品のみを抽出|
|フィルター|extargetobj|除外食品|食品オブジェクトID|指定された食品オブジェクトIDを結果から除外|
|フィルター|filtercatN|カテゴリー階層マッチ|文字列|カテゴリー文字列に完全一致したもののみ抽出。N=1～3|
|フィルター|filter_stuff|栄養素フィルター|フィルターオブジェクトの配列|栄養素の上限・下限等を指定して抽出。最大5個まで。|
|ソート|sort_id|ソート栄養素コード|栄養素コード|結果を指定した栄養素でソートする|
|ソート|sort_dir|ソート方向|許容値 asc/desc|asc=昇順/desc=降順 sort_idが指定されている場合のみ有効|
|出力制御|startpos|開始ポジション|数値|取得データ開始位置|
|出力制御|item|取得数|数値|取得データ数|
|出力制御|format|出力形式|許容値 json/csv|出力データの形式|
|出力制御|callback_method|コールバック方式|許容値 poll/push|poll=クライアントがstatusでpollingする/push=終了時指定したURLにアクセス|
|出力制御|callback_url|コールバックURL|URL(https限定)|終了時にアクセスするURL。callback_method=pushの時のみ有効|
|出力制御|callback_param|コールバックパラメータ|文字列|アクセス追加パラメータ。callback_method=pushの時のみ有効|
|出力制御|encryption|暗号化制御|有効時1|暗号化制御が「オプションに従う」の場合、暗号化の実施を指定|
|出力制御|split|出力分割|数値|出力結果数が多い場合、指定の数毎に結果を分割する。|
|入力制御|ownerexclusive|特定オーナー専有食品を検索に含む|BOOL値|特定オーナー専有食品の閲覧権利がある場合、結果に特定オーナー専有を含むようにする|

特記事項&br;
startpos = クエリー内容で抽出された内容を0から始まる行とし、指定した行から開始する&br;
inword,exword,filtersn = 複数記述する場合は半角スペースで区切って列挙&br;
exword = ブール全文検索でのみ使用可&br;
flagsn = 「商品」「外食」「テイクアウト」はメーカー名無しとして扱う&br;
exelement,inelement = 構成要素情報がない場合その食品自身を対象とする&br;
exelement,inelement,extargetobj = 複数記述する場合は半角スペースで区切って列挙&br;
callback_url = 別途アカウント作成時に指定されたURLのみに対してアクセスを発行できる&br;
split = 最大100分割までに制限され、超えた部分は破棄される

*** フィルターオブジェクト [#ebc05426]

|パラメータ名|内容|形式|省略可否など|h
|ver|フィルターオブジェクトのバージョン|数値|必須・1固定|
|type|フィルターオブジェクトのタイプ|数値|必須・filter_stuff固定|
|stuffid|対象栄養素|栄養素コード|必須・対象の栄養素コード|
|upper|栄養素の上限|数値|upper/lower/existのいずれか１つ以上必須|
|lower|栄養素の下限|数値|upper/lower/existのいずれか１つ以上必須|
|exist|栄養素の有無|include/exclude|include=存在するもののみ/exclude=存在しないもののみ&br;upper/lower/existのいずれか１つ以上必須|

*** クエリーのサンプル [#bc9585d2]

#html{{
<pre class="brush:xml;">
{
 "ver": 1,
 "type": "query",
 "inword": "カツ カレー",
 "incond": "and",
 "matching": "boolean",
 "exword": "チキン",
 "sort_id": "stuff_e",
 "sort_dir": "desc",
 "filter_stuff": [
   {
     "ver": 1,
     "type": "filter_stuff",
     "stuffid": "carbo",
     "upper": 100,
     "lower": 20
   }
 ]
}
</pre>
}}

*** レスポンス [#b188d4db]

JSONでレスポンスが返却される。

|パラメータ名|型|内容|h
|result|boolean|成功時true/失敗時false|
|batchid|string|(成功時)バッチID|
|reason|string|(失敗時)参考情報|

レスポンス例
#html{{
<pre class="brush:xml;" style="max-width:60em !important;word-break: break-all !important;">
{
 "result":true,
 "batchid":"INOYGW2NWpMaXcaqCr0Sw7WLisYu2HExwmhk2nef0JEiqP9rjmevXzuIj9xxiaLa2zdzSq849owda6y9612KIX6
hcfmU5j6h5h7vTUxiKGLhwGTQnmlskNiyNClf2Vh1"
}
</pre>
}}



** 手順 status [#l9016c71]

バッチIDを送信し、ステータスを取得する。
|~コマンド|status|
|~URL|&#104;&#116;&#116;&#112;&#115;&#58;&#47;&#47;&#40;&#65;&#80;&#73;&#12469;&#12540;&#12496;&#12540;&#21517;&#41;/services/api2/(アクセスコード)/dbbatch/status/|
|~トークン使用回数カウント|なし|

*** パラメーター一覧 [#t6554869]
|パラメータ名|内容|形式|省略可否など|h
|batchid|バッチID|文字列|必須|

*** クエリーのサンプル [#l4d462e0]

#html{{
<pre class="brush:xml;">
{
 "batchid": "INOYGW2NWpMaXcaqCr0Sw7WLisYu2HExwmhk2nef0JEiqP9rjmevXzuIj9xxiaLa2zdzSq849owda6y9612KI
X6hcfmU5j6h5h7vTUxiKGLhwGTQnmlskNiyNClf2Vh1"
}
</pre>
}}

*** レスポンス [#n86a348e]

JSONでレスポンスが返却される。ステータスが10(完了)またはエラー(90)が返されると、バッチ処理は完了となる。任意の間隔で繰り返しアクセスし、完了を待つ。

|パラメータ名|型|内容|h
|result|boolean|成功時true/失敗時false|
|batchid|string|バッチID|
|status|inegert|ステータス|
|ldate|datetime|情報の最終更新日時|
|info|string|追加情報|

status&br;
= 1:初期化済み&br;
= 2:処理開始&br;
= 3:クエリー実行中&br;
= 4:データ取り出し中&br;
= 10:完了&br;
= 90:エラー&br;

レスポンス例
#html{{
<pre class="brush:xml;">
{
 "result":true,
 "batchid":"INOYGW2NWpMaXcaqCr0Sw7WLisYu2HExwmhk2nef0JEiqP9rjmevXzuIj9xxiaLa2zdzSq849owda6y9612KIX
6hcfmU5j6h5h7vTUxiKGLhwGTQnmlskNiyNClf2Vh1",
 "status":10,
 "ldate":"2022\/10\/26 09:24:37",
 "info":"done"
}
</pre>
}}


** 手順 getinfo [#l9016c71]

ステータスが10(完了)となった処理のバッチIDを送信し、結果データセットを取得する。
|~コマンド|getinfo|
|~URL|&#104;&#116;&#116;&#112;&#115;&#58;&#47;&#47;&#40;&#65;&#80;&#73;&#12469;&#12540;&#12496;&#12540;&#21517;&#41;/services/api2/(アクセスコード)/dbbatch/getinfo/|
|~トークン使用回数カウント|なし|

*** パラメーター一覧 [#n2c8482d]
|パラメータ名|内容|形式|省略可否など|h
|batchid|バッチID|文字列|必須|

*** クエリーのサンプル [#w8fffe9e]

#html{{
<pre class="brush:xml;">
{
 "batchid": "INOYGW2NWpMaXcaqCr0Sw7WLisYu2HExwmhk2nef0JEiqP9rjmevXzuIj9xxiaLa2zdzSq849owda6y9612KI
X6hcfmU5j6h5h7vTUxiKGLhwGTQnmlskNiyNClf2Vh1"
}
</pre>
}}

*** レスポンス [#s6b130ac]

JSONでレスポンスが返却される。結果データセットは、データ完成日時から24時間保持される。&br;
splitオプション指定時は結果データが分割されるが、結果データオブジェクトの数は100個までに制限され、これを超えた部分は破棄される。


|パラメータ名|型|内容|h
|result|boolean|成功時true/失敗時false|
|batchid|string|バッチID|
|datacount|integer|結果データ総数|
|dataset|array|結果データオブジェクトの配列|
|edate|datetime|データ完成日時|

結果データオブジェクト
|パラメータ名|型|内容|h
|index|integer|データ番号|
|size|integer|ダウンロードデータサイズ|
|format|string|出力データ形式|
|plainsize|integer|復号時データサイズ(暗号化時のみ)|
|encryption|boolean|暗号化有無(暗号化時のみ)|

レスポンス例
#html{{
<pre class="brush:xml;">
{
 "result":true,
 "batchid":"INOYGW2NWpMaXcaqCr0Sw7WLisYu2HExwmhk2nef0JEiqP9rjmevXzuIj9xxiaLa2zdzSq849owda6y9612KIX
6hcfmU5j6h5h7vTUxiKGLhwGTQnmlskNiyNClf2Vh1",
 "datacount":2,
 "dataset":[
  {
   "index":1,
   "size":14477,
   "format":"json"
  },
  {
   "index":2,
   "size":24510,
   "format":"json"
  }
 ],
 "edate":"2022\/10\/26 09:24:37"
}
</pre>
}}


** 手順 getdata [#l9016c71]

手順getinfoのdataset配下にある各データをダウンロードする。
|~コマンド|getdata|
|~URL|&#104;&#116;&#116;&#112;&#115;&#58;&#47;&#47;&#40;&#65;&#80;&#73;&#12469;&#12540;&#12496;&#12540;&#21517;&#41;/services/api2/(アクセスコード)/dbbatch/getdata/|
|~トークン使用回数カウント|なし|

*** パラメーター一覧 [#t1929804]
|パラメータ名|内容|形式|省略可否など|h
|batchid|バッチID|文字列|必須|
|index|データ番号|数値|必須|

*** クエリーのサンプル [#vf786f48]

#html{{
<pre class="brush:xml;">
{
 "batchid": "INOYGW2NWpMaXcaqCr0Sw7WLisYu2HExwmhk2nef0JEiqP9rjmevXzuIj9xxiaLa2zdzSq849owda6y9612KIX
6hcfmU5j6h5h7vTUxiKGLhwGTQnmlskNiyNClf2Vh1",
 "index": 1
}
</pre>
}}

*** レスポンス [#l567252d]

クエリーで指定した形式の結果データが返却される。
jsonフォーマットについてはカスタム食品検索を参照。


レスポンス例
#html{{
<pre class="brush:xml;">
{
 "foods":[
  {
   "name":"\u30cf\u30fc\u30d5\u624b\u4ed5\u8fbc\u307f\u3055\u3055\u307f\u30ab\u30c4\u30ab\u30ec\u3
0fc(CoCo\u58f1\u756a\u5c4b)",
   "objectid":"FOba81d3e148feb3fa486ed74a",
   "unit":400,
   "stuff_e":613.4
  },
  {
  "name":"\u30ab\u30c4\u30ab\u30ec\u30fc\u3046\u3069\u3093(\u306a\u304b\u536f)",
   "objectid":"FO020fc5615440942643ea8686",
   :
 (略)
</pre>
}}

* データの規制 [#b1abac38]

|データの種類|規制|h
|バッチID|半角英数で256文字以内|


* 値渡しの特例 [#q44e247f]

[[データAPI/カスタム食品文字列検索]]との互換性のため、クエリーをGETまたはPOSTのフォームパラメーターで渡すことができる。&br;
渡すことができるのは、JSONで記述する際のオブジェクトの最上位層のプロパティであって、値がプリミティブ型（数値,文字列,食品オブジェクトID,バッチIDなど）のものに限られる。&br;
オブジェクト最上位層のプロパティ名をGETまたはPOSTのクエリ名として使用し、それぞれの値をセットする。&br;
フォームパラメーターとJSONリクエストボディを同時に使用することはできない。&br;
この特例は非推奨の機能であり、今後の機能追加に際しては対応されない可能性がある。&br;

** 例 [#lc4e584b]
 {"batchid":"abc0123","index":1} → batchid=abc0123&index=1


* splitオプションと結果データセット [#c45c32f6]

検索クエリーの内容によっては結果数が多くなる。このため、splitオプションを使用して、結果を分割して取得することが推奨される。但し、分割した結果の総数が100を超えた場合、超えた部分は破棄されるので、クライアントの処理能力が許す範囲でsplitオプションは大きく設定した方が良い。&br;
splitオプションの推奨値は10000。


* curlコマンドを使ったアクセス例 [#g30ce7dd]

#html{{
<pre class="brush:xml;">
(手順 query)
% curl -X POST \
-H 'Authorization: Bearer 4r0sM63C6t6Wsj9jAM41iIiQpzEtNySPInenKmJXnoTlt4ALF7UAFt1jKau69935fTZGrTQz
UVDIbb97slV5QahfuEA2WucBUBDYDl2rDanYfiZdhrj9cOoT' \
-H 'Content-Type: application/json' \
-d '{"ver":1,"type":"query","inword":"カレー カツ","filter_stuff":[{"ver":1,"type":"filter_stuff",
"stuffid":"stuff_e","upper": 1000,"lower": 800}]}' \
https://apidb-kag-demo07.mobadai.jp/services/api2/demo07/dbbatch/query/
{"result":true,"batchid":"7HLcQizvwZgXFKscw3av2U2aIQEf7IK5Ev24CLfJnHCrtF6ME9J4g0FwsADBuxABFo9gJMa2
rLy3o1XwTfU9F0ajULHk3sFk15xUvZYMQW5WO9X6bxOs9vrkV6Gj1sLm"}

(手順 status)
% curl -X POST \
-H 'Authorization: Bearer 4r0sM63C6t6Wsj9jAM41iIiQpzEtNySPInenKmJXnoTlt4ALF7UAFt1jKau69935fTZGrTQz
UVDIbb97slV5QahfuEA2WucBUBDYDl2rDanYfiZdhrj9cOoT' \
-H 'Content-Type: application/json' \
-d '{"batchid":"7HLcQizvwZgXFKscw3av2U2aIQEf7IK5Ev24CLfJnHCrtF6ME9J4g0FwsADBuxABFo9gJMa2rLy3o1XwTf
U9F0ajULHk3sFk15xUvZYMQW5WO9X6bxOs9vrkV6Gj1sLm"}' \
https://apidb-kag-demo07.mobadai.jp/services/api2/demo07/dbbatch/status/
{"result":true,"batchid":"7HLcQizvwZgXFKscw3av2U2aIQEf7IK5Ev24CLfJnHCrtF6ME9J4g0FwsADBuxABFo9gJMa2
rLy3o1XwTfU9F0ajULHk3sFk15xUvZYMQW5WO9X6bxOs9vrkV6Gj1sLm","status":10,"ldate":"2022\/10\/26 10:19:33
","info":"done"}

(手順 getinfo)
% curl -X POST \
-H 'Authorization: Bearer 4r0sM63C6t6Wsj9jAM41iIiQpzEtNySPInenKmJXnoTlt4ALF7UAFt1jKau69935fTZGrTQz
UVDIbb97slV5QahfuEA2WucBUBDYDl2rDanYfiZdhrj9cOoT' \
-H 'Content-Type: application/json' \
-d '{"batchid":"7HLcQizvwZgXFKscw3av2U2aIQEf7IK5Ev24CLfJnHCrtF6ME9J4g0FwsADBuxABFo9gJMa2rLy3o1XwTf
U9F0ajULHk3sFk15xUvZYMQW5WO9X6bxOs9vrkV6Gj1sLm"}' \
https://apidb-kag-demo07.mobadai.jp/services/api2/demo07/dbbatch/getinfo/
{"result":true,"batchid":"7HLcQizvwZgXFKscw3av2U2aIQEf7IK5Ev24CLfJnHCrtF6ME9J4g0FwsADBuxABFo9gJMa2
rLy3o1XwTfU9F0ajULHk3sFk15xUvZYMQW5WO9X6bxOs9vrkV6Gj1sLm","datacount":1,"dataset":[{"index":1,"siz
e":11661,"format":"json"}],"edate":"2022\/10\/26 10:19:33"}

(手順 getdata)
% curl -X POST \
-H 'Authorization: Bearer 4r0sM63C6t6Wsj9jAM41iIiQpzEtNySPInenKmJXnoTlt4ALF7UAFt1jKau69935fTZGrTQz
UVDIbb97slV5QahfuEA2WucBUBDYDl2rDanYfiZdhrj9cOoT' \
-H 'Content-Type: application/json' \
-d '{"batchid":"7HLcQizvwZgXFKscw3av2U2aIQEf7IK5Ev24CLfJnHCrtF6ME9J4g0FwsADBuxABFo9gJMa2rLy3o1XwTf
U9F0ajULHk3sFk15xUvZYMQW5WO9X6bxOs9vrkV6Gj1sLm","index":1}' \
https://apidb-kag-demo07.mobadai.jp/services/api2/demo07/dbbatch/getdata/
{"foods":[{"name":"\u30c1\u30ad\u30f3\u30ab\u30c4\u30ab\u30ec\u30fc(\u30d8\u30eb\u30b7\u30fc\u30af
\u30e9\u30b9)
...(略)
</pre>
}}

* jQueryを使ったコード例 [#pc09cb86]

#html{{
<pre class="brush:xml;">
var url = 'https://apidb-kag-demo07.mobadai.jp/services/api2/demo07/dbbatch/';
var batchid = null;
function step_query(){  //(手順 query)
  $.ajax({
    'type' : 'POST',
    'url' :  url + 'query/',
    'data' : JSON.stringify({
      "ver":1,
      "type":"query",
      "inword":"カレー カツ",
      "filter_stuff":[
        {"ver":1,"type":"filter_stuff","stuffid":"stuff_e","upper": 1000,"lower": 800}
      ]
    }),
    'processData' : false,
  })
  .success( function( resp, status, jqXHR )  // 成功時処理
  {
    if( resp.result ){
      batchid  = resp.batchid;
      step_status();
    }
  })
  .fail( function( jqXHR, status, error )  // 失敗時処理
  {
  });
}

function step_status(){  //(手順 status)
  $.ajax({
    'type' : 'POST',
    'url' :  url + 'status/',
    'data' : JSON.stringify({
      "batchid": batchid
    }),
    'processData' : false,
  })
  .success( function( resp, status, jqXHR )  // 成功時処理
  {
    if( resp.status == 90 ){
      // エラー処理
      return;
    }
    if( resp.status == 10 ){
      step_getinfo();
      return;
    }
    setTimeout(step_status,10000);
  })
  .fail( function( jqXHR, status, error )  // 失敗時処理
  {
  });
}

function step_getinfo(){  //(手順 getinfo)
  $.ajax({
    'type' : 'POST',
    'url' :  url + 'getinfo/',
    'data' : JSON.stringify({
      "batchid": batchid
    }),
   'processData' : false,
  })
  .success( function( resp, status, jqXHR )  // 成功時処理
  {
    if( resp.result ){
      for(var part of resp.dataset ){
        step_getdata(part.index);
      }
    } else {
      // エラー処理
    }
  })
  .fail( function( jqXHR, status, error )  // 失敗時処理
  {
  });
}

function step_getdata(num){  //(手順 getdata)
  $.ajax({
    'type' : 'POST',
    'url' :  url + 'getdata/',
    'data' : JSON.stringify({
      "batchid": batchid,
      "index": num
    }),
    'processData' : false,
  })
  .success( function( resp, status, jqXHR )  // 成功時処理
  {
    //データ処理
  })
  .fail( function( jqXHR, status, error )  // 失敗時処理
  {
  });
}
</pre>
}}


* 考慮事項 [#wa8c2055]

本APIはクエリーの内容に依存して実行時間が極めて長くなる可能性がある。&br;
また、結果数が多くなる可能性がある。&br;
本APIの返却するデータは、クライアント側で適切にキャッシュ等を行い、アクセス量を低減させることが望ましい。&br;

* バージョン [#o0becc47]

このドキュメントのバージョン情報
|Version|1|
|Revision|1|
|Editor|west|
DBAPI/食品検索 の変更点

DBAPI/食品検索の変更点
