-
Notifications
You must be signed in to change notification settings - Fork 3
API Documentation
Chihjen Ko edited this page Nov 27, 2018
·
30 revisions
已停止更新。請到各相關章節編輯。
https://api-dev.camera-trap.tw/v0.8
前端登入 AWS 後隨即應將 idToken 送給後端，讓後端也有相應權限
- endpoint
/ctp-user/sign-in - post data
{"idToken": $idToken} - response
{"ret": $user_id}
@TODO：定期用 refreshToken 更新登入狀態
- endpoint
GET /ctp-user/me - response
{
"ret": {
"user_id": "OrcID_0000-0002-7446-3249",
"name": "Thomas Yu",
"email": "diabloevagto@gmail.com",
"created": 1541310244.411,
"modified": 1542562247.975
}
}
列出與已登入使用者相關的計畫
- endpoint
/project/related-to-me - post data
Optional, null or{"sort_key": "projectTitle"} - response
{"ret": [$project_metadata, ...]}
列出單一計畫的所有訊息 (含樣區、子樣區與相機位置)
- endpoint
GET
project/${projectTitle}
- endpoint
/announcement/bulk-insert - post data
{
"message": 公告內容,
"announcement_type": 公告類型，目前只有 SYSTEM,
"level": 公告等級，暫時先分 INFO, WARNING,
"target_id": optional, 先不管這個
}
- response
- endpoint
/announcement/query - post data 讀取最近 3 筆 (可自行改 limit)
{
"query":{},
"limit": 3,
"sort": {"modified": -1}
}
- response
{ ret: [$announcement]}
- endpoint
/project/summary-of-all - response
{
"ret": [
{
"members": [
"OrcID_0000-0002-7446-3249"
],
"funder": "",
"coverImage": null,
"earliestRecordTimestamp": null,
"projectTitle": "asasasas"
},
{
"members": [
"OrcID_0007-0183-5566-2266"
],
"funder": "林務局",
"coverImage": "http://example.org/kinda_animal_cover.jpg",
"earliestRecordTimestamp": null,
"projectTitle": "狂犬病監測"
},
{
"members": [
"OrcID_0000-0002-7446-3249"
],
"funder": "測試-承辦單位",
"coverImage": null,
"earliestRecordTimestamp": null,
"projectTitle": "測試-計畫名稱計畫名稱計畫名稱計畫名稱"
},
{
"members": [
"OrcID_0000-0002-7446-3249",
"OrcID_0000-0003-1335-0184"
],
"funder": "林務局",
"coverImage": null,
"earliestRecordTimestamp": null,
"projectTitle": "測試計畫1"
}
]
}
由於權限控制機制會依使用者在特定計畫的角色決定使用者可進行的操作，使用者在新增計畫前必須要被設定為新計畫的 Project Manager。前提是計畫名稱不存在，也沒有其他使用者擁有與此計畫相關的任何角色。
- endpoint
/project/init - post data
{"projectTitle": "新計畫的名稱"} - response
default db response
bulk-insert 或 bulk-replace： bulk-* 系列的操作，post data 的 json root 都是 array，必要時可批次操作；
- endpoint
/project/bulk-insert - post data
[
{
"projectTitle": "測試計畫1 // 計畫名稱",
"shortTitle": "測1 // 計畫簡稱",
"funder": "林務局 // 委辦單位",
"projectId": "FB-test-cameratrap-01 // 計畫編號",
"principalInvestigator": "測試principalInvestigator // 計畫主持人",
"projectStartDate": "2018-10-15 // 計畫時間：起",
"projectEndDate": "2018-12-10 // 計畫時間：迄",
"adminArea": [ // 計畫地區, 見 WF 2.3.7
"苗栗縣",
"新竹縣"
],
"abstract": "// 計畫摘要",
"remarks": "// 備註",
"coverImage": "http://example.org/kinda_animal_cover.jpg //計畫封面",
"license": { 創用 CC 授權 // WF 2.3.11 ~ WF 2.3.13
"metadata": "CC BY 4.0", // 詮釋資料授權
"data": "CC BY 4.0", // 鑑定資訊授權
"multimedia": "CC BY-NC 4.0" // 影像資料授權
},
"dataFieldEnabled": [ // 欄位設定 WF 3.2.1
"sex", // 性別
"lifeStage", // 年齡
"antler", // 角況
"remarks" // 備註
],
"cameraLocations": [
{
"fullCameraLocationMd5": "md5 string of `$projectTitle/$site/$subSite/$cameraLocation`, use `NULL` for null value",
"projectTitle": "測試計畫1",
"site": "苗栗",
"subSite": "南庄鄉田美村",
"cameraLocation": "HC20A",
"original_x": "122",
"original_y": "23.5",
"original_geodatum": "wgs84",
"elevation": 56,
"wgs84dec_x": 122,
"wgs84dec_y": 23.5,
"twd97tm2_x": 223456,
"twd97tm2_y": 2345678,
"dailyTestTime": [ // 可先略過這項
{
"since": 1539593959,
"time": "12:00:00"
}
],
"vegetation": "榕楠林帶",
"land_cover": "森林"
}
],
"dailyTestTime": [
{
"since": 1539593959,
"time": "12:00:00"
}
],
"timezone": "+8",
"dataPublicDate": "// 資料公開日期，計畫起始時間的兩年後"
}
]
- response
default db response
let adminAreaOptions = [
"台北市",
"新北市",
"桃園市",
"台中市",
"台南市",
"高雄市",
"基隆市",
"新竹市",
"嘉義市",
"新竹縣",
"苗栗縣",
"彰化縣",
"雲林縣",
"嘉義縣",
"屏東縣",
"宜蘭縣",
"花蓮縣",
"台東縣",
"澎湖縣",
"金門縣",
"連江縣"
];
let adminAreaOptions = [
"CC0", // 無著作權 (CC0)
"CC BY 4.0", // 姓名標示
"CC BY-NC" // 姓名標示-非商業性
];
fullCameraLocationMd5 與 site 值為 optional, 若不給定此值，則會針對所有 sites 與 camera locations 進行統計
- endpoint
/project/location-month-identified-num - post data
{
"year": 2017,
"projectTitle": "測試計畫1",
"site": "新竹", // optional
"fullCameraLocationMd5": "4d3d38693056909db46c564531a63e8c" // optional
}
- response
{
"ret": [
{
"_id": "4d3d38693056909db46c564531a63e8c",
"projectTitle": "測試計畫1",
"site": "新竹",
"subSite": "南庄30林班",
"cameraLocation": "HC21A",
"monthly_num": [
{
"month": 3,
"num": 6
},
{
"month": 2,
"num": 115
},
{
"month": 1,
"num": 21
}
],
"fullCameraLocationMd5": "4d3d38693056909db46c564531a63e8c",
"wgs84dec_x": 122.563,
"wgs84dec_y": 23.7
}
]
}
fullCameraLocationMd5 與 site 值為 optional, 若不給定此值，則會針對所有 sites 與 camera locations 進行統計
- endpoint
/project/location-month-retrieved-num - post data
{
"year": 2017,
"projectTitle": "測試計畫1",
"site": "新竹", // optional
"fullCameraLocationMd5": "4d3d38693056909db46c564531a63e8c" // optional
}
- response
{
"ret": [
{
"_id": "4d3d38693056909db46c564531a63e8c",
"projectTitle": "測試計畫1",
"site": "新竹",
"subSite": "南庄30林班",
"cameraLocation": "HC21A",
"monthly_num": [
{
"month": 3,
"num": 6
},
{
"month": 2,
"num": 115
},
{
"month": 1,
"num": 21
}
],
"fullCameraLocationMd5": "4d3d38693056909db46c564531a63e8c",
"wgs84dec_x": 122.563,
"wgs84dec_y": 23.7
}
]
}
- endpoint /abnormal-data/bulk-replace
- post data
[{
"projectTitle": "測試計畫1", // 計畫名稱
"site": "新竹", // 樣區
"subSite": "南庄30林班", // 子樣區
"cameraLocation": "HC20A", // 相機位置
"fullCameraLocationMd5": md5("$projectTitle/$site/$subSite/cameraLocation"), // 前端產生, $subSite 若為空值，帶入字串的 'NULL',
"abnormalStartDate": "2017/02/08", // 異常資料時間 起
"abnormalEndDate": "2017/03/01", // 異常資料時間 迄
"abnormalType": 選自 `相機故障 (空拍過多)`, `相機故障 (沒有影像)`, `相機失竊`, `相機電量耗損過快`, `其他`,
"remarks": "備註"
}]
- response
- endpoint
/project/location-month-abnormal - post data
{
"projectTitle": "測試計畫1",
"year": 2017,
"site": "新竹", // 20181108 已改為 optional
"fullCameraLocationMd5": optional
}
- response
{
"ret": [
{
"projectTitle": "測試計畫1",
"site": "新竹",
"subSite": "南庄30林班",
"cameraLocation": "HC21A",
"fullCameraLocationMd5": "4d3d38693056909db46c564531a63e8c",
"wgs84dec_x": 121.5,
"wgs84dec_y": 23.56,
"year": 2017,
"month": [
3,
2
],
"abnormalType": "其他",
"abnormalStartDate": "2017/02/08",
"abnormalEndDate": "2017/03/01",
"remarks": "資料沒錯，只是測試用"
}
]
}
-
endpoint
/project/image-species-group -
post data
{
"projectTitle": "$projectTitle" // 計畫名稱，例如：測試計畫1
}
- response
{
"ret": [
{
"species_group": [
{
"species": "松鼠",
"count": 3
},
{
"species": "獼猴",
"count": 63
},
{
"species": "食蟹獴",
"count": 3
},
{
"species": "無法辨識",
"count": 3
},
...,
{
"species": "鼬獾",
"count": 150
}
],
"total": 1895,
"modified": 1542014476.298
}
]
}
這塊先跳過
如果確定文件存在，只想修改其中特定欄位，例如：增加欄位、地點，則改用 bulk-update，並需要特定的 spec for access control _id： 必要篩選條件，篩選出欲更新的目標文件； projectTitle：權限管控並保護資料一致性，不會真的用在資料更新上 $set： 設定文件屬性值。
- endpoint
/project/bulk-update - post data
[{
"_id": "測試計畫1",
"projectTitle": "測試計畫1",
"$set": {
"dataFieldEnabled": [ // 欄位設定 WF 3.2.1.b, WF 3.2.1.d, WF 3.2.1.e
"sex", // 性別
"lifeStage", // 年齡
"antler", // 角況
"remarks" // 備註
],
"speciesList": [ // 常見物種順序 WF 3.3.2, default 值如下
"空拍",
"定時測試",
"工作照",
"山羌",
"水鹿",
"獼猴",
"鼬獾",
"山羊",
"野豬",
"鼠類",
"白鼻心",
"人",
"藍腹鷴",
"食蟹獴",
"狗"
],
"cameraLocations": [ // 相機位置管理 WF 3.4, WF 3.5
{
"fullCameraLocationMd5": "這是算出來的 camera location id, md5 string of `$project/$site/$sub_site/$location`, use string `NULL` for null value",
"projectTitle": "測試計畫1 // 計畫名稱",
"site": "苗栗 // 樣區",
"subSite": "南庄鄉田美村 // 子樣區",
"cameraLocation": "HC20A // 相機位置",
"original_x": "122", // 使用者輸入的原始 x 值
"original_y": "23.5", // 使用者輸入的原始 y 值
"original_geodatum": "WGS84" // 使用者選定的大地基準 WF 3.4.4,
"elevation": 56, // 海拔(公尺)
"wgs84dec_x": 122, // (轉換後的) WGS84 十進位經度座標
"wgs84dec_y": 23.5, // (轉換後的) WGS84 十進位緯度座標
"twd97tm2_x": 223456, // (轉換後的) TWD97TM2 X值
"twd97tm2_y": 2345678, // (轉換後的) TWD97TM2 Y值
"dailyTestTime": [ // 可先略過這個
{
"since": 1539593959,
"time": "12:00:00"
}
],
"vegetation": "榕楠林帶", // 植被
"land_cover": "森林" // 土地覆蓋類型
},
{ // 另一個相機地點
"fullCameraLocationMd5": "another location ...",
...
},
...
]
}
}]
- endpoint
GET /data-field-available
或已知當下在編輯 cameraLocations 下的特定 array item, 例如設定第 2 個 item
[{
"_id": "測試計畫1",
"projectTitle": "測試計畫1",
"$set": {
"cameraLocations.2": {
"fullCameraLocationMd5": "md5 string of `$project/$site/$sub_site/$location`, use `NULL` for null value",
"projectTitle": "測試計畫1",
"site": "苗栗",
"subSite": "南庄鄉田美村",
"cameraLocation": "HC20A",
"original_x": "122",
"original_y": "23.5",
"original_geodatum": "wgs84",
"elevation": 56,
"wgs84dec_x": 122,
"wgs84dec_y": 23.5,
"twd97tm2_x": 223456,
"twd97tm2_y": 2345678,
"dailyTestTime": [
{
"since": 1539593959,
"time": "12:00:00"
}
],
"vegetation": "榕楠林帶",
"land_cover": "森林"
}
}
}]
[{
"_id": "測試計畫1",
"projectTitle": "測試計畫1",
"$set": {
"cameraLocations.2.wgs84dec_x": 122.56, // 原本是 122
"cameraLocations.2.elevation": 78 // 原本是 56
}
}]
- response
default db response
檔案上傳 WF 5.3
- fullCameraLocationMd5 檔案上傳時，會需要替每個待上傳的檔案設定 site、subSite、cameraLocation等資訊，加上 projectTitle，即可產生 fullCameraLocationMd5 md5(projectTitle/site/subSite/cameraLocation)，計畫設定上若不需要填寫 subSite，補上字串的 'NULL'
- upload session id 替每個檔案產生一個 uuid v4 的 upload session id ($sessid)
於前端產生 upload session id (uuid v4) 值，以下簡稱 sessid，並依檔案類型上傳至以下位置 (暫時稱為 $PATH_PREFIX)：
ZIP：upload/$sessid/zip/
CSV：upload/$sessid/csv/
JPG：upload/$sessid/image/
MP4/AVI：upload/$sessid/video/
只在以下幾個情境需要更新上傳事件狀態：
- 開始上傳時將狀態設為 WAITING
- 成功時更新為 SUCCESS
- 失敗 FAILED
- 取消 CANCELLED
- endpoint
/upload-session/bulk-update - post data
[
{
_id: $sessid,
projectTitle: projectTitle,
$set: {
status: SUCCESS|FAILED|WAITING|CANCELLED
},
$setOnInsert: {
fullCameraLocationMd5: $fullCameraLocationMd5,
projectTitle: $projectTitle,
site: $site,
subSite: $subSite,
cameraLocation: $cameraLocation
by: $user_id,
file: $PATH_PREFIX + file.name
},
$upsert: true
}
]
- response
default db response
於前端上傳檔案至 AWS S3 時，加入 projectTitle, site, subSite, cameraLocation, user_id 等 tags；如果 subSite 是空值，請填入字串的 'NULL'
let bucket = 'camera-trap';
let key = $PATH_PREFIX + file.name;
// 替每個上傳檔設定 uploader
let uploader = new AWS.S3.ManagedUpload({
params: {Bucket: bucket, Key: key, Body: file},
tags: [
{Key: "projectTitle", Value: $project},
{Key: "site", Value: $site},
{Key: "subSite", Value: $subSite},
{Key: "cameraLocation", Value: $cameraLocation},
{Key: "user_id", Value: $user_id}
]
});
let seErrHandler = function (err, data) {
...
}
uploader.send(s3ErrHandler);
uploader.on('httpUploadProgress', function(progress) {
console.log((100 * progress.loaded / progress.total) + '%');
// console.log(progress);
});
query：查詢條件 projection：回傳欄位 (default 是回傳完整文件)
- endpoint
/media/annotation/query - post data
{
"query": {
"related_upload_sessions": $sessid
}
}
- response
{"ret": [ $multimedia_annotation, ... ]}
顯示與登入使用者相關的上傳操作紀錄
- endpoint
GET /upload-session/mine - response
{
"ret": [
{
"_id": "test_upload_session_02",
"upload_session_id": "test_upload_session_02",
"projectTitle": "測試計畫1",
"fullCameraLocationMd5": "263d239eb09fa3b607f4846e67b91ba3",
"status": "ERROR",
"by": "OrcID_0000-0002-7446-3249",
"modified": 1542009001.994,
"messages": [ // 詳細錯誤訊息
{
"key": "upload/test_upload_session_02/csv/TD06B.csv",
"errors": [
"上傳資料與過往資料重疊，暫不匯入."
],
"modified": 1541750623.705,
"problematic_ids": [潛在有問題的資料ID, ...],
},
{
"key": "upload/test_upload_session_02/csv/TD03A.csv",
"errors": [
"上傳資料與過往資料重疊，暫不匯入."
],
"modified": 1541750915.423,
"problematic_ids": [潛在有問題的資料ID, ...],
},
...
],
"file": "上傳的那個檔案",
"created": 1540788756.494,
"modified": 1542014471.609,
}
]
}
計畫成員 WF 3.6
OrcID 不提供 email 資訊，沒辦法用 email 加人，先做使用 OrcID 加人
- endpoint
/project/add-user-to-project - post data
{
"user_id": $user_id, // OrcID_XXXX-XXXX-XXXX-XXXX
"projectTitle": $projectTitle, // 欲加入的計畫名稱
"role": $role // 角色，待建立對應表
}
- response
default db response
// 計畫相關角色 (允許在 3.6.1.1 加入)
ProjectManager 計畫管理員
Researcher 研究人員
ResearchAssistant 研究助理
CaseOfficer 林管處承辦人
// 機能型角色 (不允許在 3.6.1.1 加入)
SysAdmin 系統管理員
ProjectInitiator 可建立新計畫的人
- endpoint
/ctp-user/query - post data
{
"query": {
"project_roles.projectTitle": $projectTitle,
"project_roles.roles": {"$in": ["ProjectManager", "Researcher", "ResearchAssistant", "CaseOfficer"]}
}
}
- response
{"ret": [ $ctp-user ]}
暫時略過刪除，API 開發中
資料編輯 WF 4
目前設計是針對檔案，由於每個檔案可能有 1N 個 tokens，故每個 revisions 也可能有 1N 個 tokens。
- endpoint
/annotation-revision/query - post data
{
"query": {
"_id": "11053ee0ec864feca68e7bf8932dd23e" // url_md5 = _id from WF 4.2 /media/annotation/query
},
"sort": {
"revisions.created": 1
}
}
- response
{
"results": [
{
"_id": "11053ee0ec864feca68e7bf8932dd23e",
"revisions": [
{
"modifiedBy": "OrcID_0000-0002-7446-3249",
"created": 1542014474.531,
"tokens": [
{ // 可直接用於 restore 的資料單元
"data": [
{
"key": "species",
"label": "物種",
"value": "山羌",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "sex",
"label": "性別",
"value": "NA",
"data_error_flag": true,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "lifeStage",
"label": "年齡",
"value": "NA",
"data_error_flag": true,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "id",
"label": "id",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "category",
"label": "category",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "sciName",
"label": "sciName",
"value": "Muntiacus reevesi micrurus",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "behavior",
"label": "behavior",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
}
],
"summary": { // 用於介面顯示的 revision 摘要
"species": "山羌",
"sex": "NA",
"lifeStage": "NA",
"id": "NA",
"category": "NA",
"sciName": "Muntiacus reevesi micrurus",
"behavior": "NA"
}
},
{ // 同張照片的第 2 筆 record
"data": [
{
"key": "species",
"label": "物種",
"value": "山羌",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "sex",
"label": "性別",
"value": "NA",
"data_error_flag": true,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "lifeStage",
"label": "年齡",
"value": "non-adult",
"data_error_flag": true,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "id",
"label": "id",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "category",
"label": "category",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "sciName",
"label": "sciName",
"value": "Muntiacus reevesi micrurus",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "behavior",
"label": "behavior",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
}
],
"summary": { // 同照片第二筆資料用於介面顯示的摘要
"species": "山羌",
"sex": "NA",
"lifeStage": "non-adult",
"id": "NA",
"category": "NA",
"sciName": "Muntiacus reevesi micrurus",
"behavior": "NA"
}
}
]
}
],
"url_md5": "11053ee0ec864feca68e7bf8932dd23e"
}
]
}
- endpoint
/annotation-revision/restore - post data
{
"url_md5": "11053ee0ec864feca68e7bf8932dd23e",
"revision_tokens": [ // 選定要還原的 revision 下的 tokens 直接搬過來，其餘後端處理
{
"data": [
{
"key": "species",
"label": "物種",
"value": "山羌",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "sex",
"label": "性別",
"value": "NA",
"data_error_flag": true,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "lifeStage",
"label": "年齡",
"value": "NA",
"data_error_flag": true,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "id",
"label": "id",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "category",
"label": "category",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "sciName",
"label": "sciName",
"value": "Muntiacus reevesi micrurus",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "behavior",
"label": "behavior",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
}
],
"summary": {
"species": "山羌",
"sex": "NA",
"lifeStage": "NA",
"id": "NA",
"category": "NA",
"sciName": "Muntiacus reevesi micrurus",
"behavior": "NA"
}
},
{
"data": [
{
"key": "species",
"label": "物種",
"value": "山羌",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "sex",
"label": "性別",
"value": "NA",
"data_error_flag": true,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "lifeStage",
"label": "年齡",
"value": "non-adult",
"data_error_flag": true,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "id",
"label": "id",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "category",
"label": "category",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "sciName",
"label": "sciName",
"value": "Muntiacus reevesi micrurus",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
},
{
"key": "behavior",
"label": "behavior",
"value": "NA",
"data_error_flag": false,
"last_validated_timestamp": 1542014471.053,
"unit": "",
"context": "camera-trap"
}
],
"summary": {
"species": "山羌",
"sex": "NA",
"lifeStage": "non-adult",
"id": "NA",
"category": "NA",
"sciName": "Muntiacus reevesi micrurus",
"behavior": "NA"
}
}
]
}
- response
default mongodb response
fullCameraLocationMd5 optional, 拿掉此值會得到所有相機位置資料 date_time_corrected_timestamp optional
- endpoint /media/annotation/query
- post data
{
"query": {
"projectTitle": "測試計畫1",
"site": "苗栗",
"fullCameraLocationMd5": {
"$in": [fullCameraLocationMd5_1, ...]
},
"date_time_corrected_timestamp": {
"$gte": 4.2.1.c 選取的起始時間timestamp, optional
"$lte": 4.2.1.c 選取的結束時間timestamp, optional
}
},
"projection": {
"projectTitle": true,
"site": true,
"subSite": true,
"cameraLocation": true,
"fullCameraLocationMd5": true,
"tokens.data.key": true,
"tokens.data.label": true,
"tokens.data.value": true,
"corrected_date_time": true,
"date_time_corrected_timestamp": true,
"url": true,
"low_quality_url": true,
"imageUrlPrefix": true
},
"limit": 1000, // 視前端效能調整數字, WF 4.6.1.a
"skip": 0 (for page 1, 1000 for page 2, ... etc.)
}
- response
limit 與 skip 限制的是回傳的 results 數，單位是多媒體標註文件 media annotation(以下簡稱annotation)。 annotation 下會有 tokens，每個 token 是表格資料裡的一個 row。 tokens.data 的每個物件即額外欄位
表格資料欄位與對應的回傳資料：
date_time_corrected_timestamp 便於計算連續照片是否為連拍用
不允許內容更動的欄位 -- 樣區：$site + ["-" + subSite] -- 相機位置：$cameraLocation -- 檔名：base name of $url -- 時間：$corrected_date_time 允許內容更動的欄位 -- tokens.data
Required: -- 物種: data.key == species 其他要顯示的部分(含要顯示的欄位與順序)，請參考計畫啟用的自訂欄位 project.dataFieldEnabled -- 性別: data.key == sex -- 年齡: data.key == lifeStage -- 角況: data.key == antler -- 備註: data.key == remarks 除了以上必要欄位與啟用的自訂欄位，剩下的都「不要顯示」在編輯表單
{
"results": [
...,
{
"_id": "11053ee0ec864feca68e7bf8932dd23e",
"tokens": [
{
"data": [
{
"key": "species",
"value": "山羌",
"label": "物種"
},
{
"key": "sex",
"value": "NA",
"label": "性別"
},
{
"key": "lifeStage",
"value": "NA",
"label": "年齡"
},
{
"key": "id",
"value": "NA",
"label": "id"
},
{
"key": "category",
"value": "NA",
"label": "category"
},
{
"key": "sciName",
"value": "Muntiacus reevesi micrurus",
"label": "sciName"
},
{
"key": "behavior",
"value": "NA",
"label": "behavior"
}
]
},
{
"data": [
{
"key": "species",
"value": "山羌",
"label": "物種"
},
{
"key": "sex",
"value": "NA",
"label": "性別"
},
{
"key": "lifeStage",
"value": "non-adult",
"label": "年齡"
},
{
"key": "id",
"value": "NA",
"label": "id"
},
{
"key": "category",
"value": "NA",
"label": "category"
},
{
"key": "sciName",
"value": "Muntiacus reevesi micrurus",
"label": "sciName"
},
{
"key": "behavior",
"value": "NA",
"label": "behavior"
}
]
}
],
"url": "images/orig/測試計畫1/苗栗/南庄鄉田美村/HC20A/IMG_0064_1486661309.jpg",
"url_md5": "11053ee0ec864feca68e7bf8932dd23e",
"projectTitle": "測試計畫1",
"site": "苗栗",
"subSite": "南庄鄉田美村",
"cameraLocation": "HC20A",
"fullCameraLocationMd5": "e6d9c06937a24d9db8ac9a431b89aa17",
"corrected_date_time": "2017-02-09 17:28:29",
"low_quality_url": "some low quality image url",
"imageUrlPrefix": "https://....."
}
...
]
}
查詢相機位置資料已上鎖/上鎖者是誰
- endpoint
/camera-location/data-lock/locked - post data
{
"projectTitle": "測試計畫1", // required 計畫名稱
"site": "苗栗", // optional 樣區名稱
"subSite": "南庄30林班", // optional 子樣區名稱
"fullCameraLocationMd5": null, // optional 相機位置 ID
}
- response
{
"ret": [
{
"cameraLocationDataLock": {
"fullCameraLocationMd5": "e6d9c06937a24d9db8ac9a431b89aa17",
"projectTitle": "測試計畫1",
"locked": true,
"locked_by": {
"user_id": "OrcID_0000-0002-7446-3249",
"name": "Thomas Yu",
"email": "XXXX@XXXX.XXX"
},
"locked_on": 0,
"site": "苗栗",
"subSite": "南庄鄉田美村",
"cameraLocation": "HC20A"
}
},
{
"cameraLocationDataLock": {
"fullCameraLocationMd5": "8c0223d81f4958ddc3a776e0c7337e4c",
"projectTitle": "測試計畫1",
"locked": true,
"locked_by": {
"user_id": "OrcID_0000-0002-7446-3249",
"name": "Thomas Yu",
"email": "XXXX@XXXX.XXX"
},
"locked_on": 0,
"site": "苗栗",
"subSite": "南庄鄉田美村",
"cameraLocation": "HC20B"
}
},
{
"cameraLocationDataLock": {
"fullCameraLocationMd5": "4d3d38693056909db46c564531a63e8c",
"projectTitle": "測試計畫1",
"locked": true,
"locked_by": {
"user_id": "OrcID_0000-0002-7446-3249",
"name": "Thomas Yu",
"email": "XXXX@XXXX.XXX"
},
"locked_on": 0,
"site": "新竹",
"subSite": "南庄30林班",
"cameraLocation": "HC21A"
}
}
]
}
fullCameraLocationMd5：相機地點 id projectTitle：計畫名稱，除了當雙保險，還用來限制本操作的權限
後端機制會在 bulk-replace 批次更新相機位置上鎖狀態前，檢查相機位置是否已被其他人鎖定。欲鎖定的多個相機位置中，只要有一個已被他人鎖定，整個鎖定流程都會失敗
- endpoint
/camera-location/data-lock/bulk-replace - post data
[
{
"fullCameraLocationMd5": "4d3d38693056909db46c564531a63e8c", // 相機位置 id
"projectTitle": "測試計畫1", // 計畫名稱
"locked": false, // 上鎖 true / 解鎖 false
},
{
// 更多相機位置
},
...
]
- response
default db response
更新 WF 4.2 response 的資料 annotation > tokens[] > data[] 使用者上傳的資料有可能包含不在 WF 3.2 允許的欄位，需要將之保留，因此要用特定的 update 寫法。
- endpoint
/media/annotation/bulk-update - post data 根據 WF 4.2 回傳的資料（要注意 array items 的順序）修改現有的 tokens.data
[
{
"_id": "11053ee0ec864feca68e7bf8932dd23e", // annotation 中的 _id 或 url_md5 (兩個值相同)
"projectTitle": "測試計畫1", // annotation 中的 projectTitle
"fullCameraLocationMd5": "e6d9c06937a24d9db8ac9a431b89aa17", // annotation 中的 fullCameraLocationMd5
"$set": {
"tokens.0.data.2.value": "Adult", // 設定annotation下的第1個token的第3項資料值
"tokens.1.data.1.value": "F" // 設定annotation下的第2個token的第2項資料
}
},
{
// 更新另一個 annotation 資料
},
...
]
複製一列並貼上 by 增加一組 tokens, WF 4.10.2, WF 4.10.3
[
{
"_id": "11053ee0ec864feca68e7bf8932dd23e",
"projectTitle": "測試計畫1",
"fullCameraLocationMd5": "e6d9c06937a24d9db8ac9a431b89aa17",
"$push": {
"tokens": {
"data": [
{
"key": "species",
"label": "物種",
"value": // 複製過來的值,
},
{
// 其他複製過來的 data
},
...
],
"token_id": uuid(),
"species_shortcut": "...", // data.key == species 的 data.value
"bbox": {
"full_scope": true,
"original_point": "topleft"
},
"meta": {
"virtual_individual_id": uuid(),
"virtual_part_id": uuid()
}
"description_level": "individual",
"token_error_flag": true // 複製過來的值,
"video_paused_at": null
}
}
},
{
// 針對更多的 annotations ...
},
...
]
- response
default db response
含必要欄位 (species)、已啟用的自訂欄位 (dataFieldEnabled) 與欄位允許內容資訊
-
endpoint
/project/data-fields -
post data
{
"projectTitle": "測試計畫1"
}
- response
{
"ret": [
{
"_id": null,
"speciesList": [ // 必填欄位，label:物種, key:species
"山羌",
"水鹿",
"鼬獾",
"定時測試",
"工作照",
"空拍"
],
"dailyTestTime": [ // 每日拍攝測試照的時間, 24 時制
{
"since": 1539593959,
"time": "12:00:00"
}
],
"fieldDetails": [ // 其他啟用欄位
{
"_id": "lifeStage",
"key": "lifeStage",
"label": "年齡",
"description": "string",
"widget_type": "select", // 如果是 select, 則會需要 options
"widget_select_options": [
"Young",
"Adult",
"Unknown"
],
"created": 1541401451.944,
"modified": 1541401451.944,
"widget_date_format": null
},
{
"_id": "sex",
"key": "sex",
"label": "性別",
"description": "string",
"widget_type": "select",
"widget_select_options": [
"M",
"F",
"Unknown"
],
"created": 1541401451.944,
"modified": 1541401451.944,
"widget_date_format": null
},
{
"_id": "antler",
"key": "antler",
"label": "角況",
"description": "string",
"widget_type": "select",
"widget_select_options": [
"TBD",
"Unknown"
],
"created": 1541401451.944,
"modified": 1541401451.944,
"widget_date_format": null
},
{
"_id": "remarks",
"key": "remarks",
"label": "備註",
"description": "其他相關內容",
"widget_type": "text", // 文字欄位，不做任何內容檢查
"created": 1541401451.944,
"modified": 1541401451.944,
"widget_select_options": null,
"widget_date_format": null
}
]
}
]
}
bulk-update 方法需要特定的 spec for access control _id： update 的對象 projectTitle：權限管控並保護資料一致性，不會真的用在資料更新上 fullCameraLocationMd5：同 project $set：裡面若有設定 project 與 fullCameraLocationMd5，後端會為了維護一致性將之清除
- endpoint
/media/annotaion/bulk-update - post data
[{
"_id": $url_md5,
"projectTitle": $projectTitle,
"fullCameraLocationMd5": $fullCameraLocationMd5,
"$set": {
"tokens": [
{
"data": [
{
"label": "物種",
"key": "species",
"value": "鼬獾",
"unit": "",
"data_error_flag": false|true,
"last_validated_timestamp": now(),
"context": "camera-trap"
},
{
// 其他 data
},
...
],
"species_shortcut": "鼬獾",
... // 其他屬性維持不變
},
{
// 其他 tokens
},
...
]
}
}]
- endpoint
/media/annotation/query - post data MongoDB 的 find patterns，可利用 limit 與 skip 分頁。
{
"query": {
"$or": [
{
"$and": [
{
"tokens.data.key": "species"
},
{
"$or": [
{
"tokens.data.value": "鼬獾"
},
{
"tokens.data.value": "鼬貛"
}
]
}
]
},
{
"$and": [
{
"tokens.data.key": "life-stage"
},
{
"tokens.data.value": "young"
}
]
}
]
},
"
ion": {
"url": "$url",
"projectTitle": "$projectTitle",
"cameraLocation": "$cameraLocation"
},
"limit": 1000,
"skip": 5000
}
- response
{
"ret": [
{
"type": "StillImage",
"url": "string",
"url_md5": "string",
"multimedia_error_flag": false,
"related_upload_sessions": [],
"tokens": [
{
"token_id": "string",
"token_error_flag": false,
"species_shortTitlecut": "string",
"description_level": "individual",
"bbox": {
"full_scope": true,
"original_point": "topleft"
},
"meta": {
"virtual_individual_id": "string",
"virtual_part_id": "string"
},
"data": [
{
"key": "",
"label": "",
"value": "",
"unit": "",
"data_error_flag": false,
"last_validated_timestamp": 0,
"context": "camera-trap"
}
]
}
],
"projectTitle": "string",
"site": "string",
"subSite": "",
"cameraLocation": "string",
"fullCameraLocationMd5": "string",
"timezone": "string",
"date_time_original": "string",
"date_time_original_timestamp": 0,
"year_original": "string",
"month_original": "string",
"day_original": "string",
"hour_original": "string",
"create_date": "string",
"wgs84dec_x": 0,
"wgs84dec_y": 0
}
]
}
需要先登入，才會得到完整的個人化資訊；否則只會看到系統通知(collection==Announcement)。 回傳的 collection 屬性對應到 MongoDB 的資料表。也提供使用者點選通知時，介面上應如何反應的依據。collection 為 UploadSession 者會多一個 status 屬性代表上傳結果。回傳結果預設照 modified 降冪排序。
- endpoint
GET /announcement/notifications - response
{
"ret": [
{
"_id": "test_upload_session_02",
"status": "ERROR",
"modified": 1542706883.083,
"created": 1541750624.016,
"level": "WARNING",
"message": "測試計畫1 臺東處-NULL<br/>TD03A 2018-01-01 00:00:00-2018-03-23 11:07:20",
"collection": "UploadSession"
},
{
"_id": "69d10deccf4b8f449204731df940ca57",
"message": "(使用者) 回報相機異常：相機電量耗損過快<br/>測試計畫1 新竹-南庄30林班<br/>HC21A 2018/10/01-2018/11/16",
"level": "WARNING",
"modified": 1542563213.889,
"created": 1542563213.889,
"collection": "AbnormalData"
},
...
{
"_id": "06fc82ba-2ea6-433e-9980-c5b9c7e04d44",
"message": "系統今夜緊急維修，請暫停使用",
"level": "WARNING",
"created": 1541508803.35,
"modified": 1541508803.35,
"collection": "Announcement"
},
...
]
}
- endpoint /user-report/submit
- post data
{
"reportType": 問題回報/意見反饋,
"reportContentType": 系統操作/帳號相關/計畫管理/檔案上傳/資料編輯/篩選及下載/其他問題,
"description": 問題描述,
"email": 電子郵件,
"attachments": [上傳到S3的附件連結們,...]
}
- response
default db response