MRS 核心 REST API
本書提供在您啟用 REST 後，使用 MySQL REST 服務查詢及其他針對資料表和檢視表的操作範例。
章節概觀
另請參閱
- MySQL REST 服務 - 開發人員指南 - 本書說明如何安裝和設定 MySQL REST 服務 (MRS)，以及如何透過 REST 呼叫存取資料。
- MySQL REST 服務 - SDK 參考 - 本書說明如何使用 MRS 軟體開發套件，並討論用戶端 API。
- MySQL REST 服務 - SQL 參考 - 本書討論 MySQL REST 服務 SQL 擴充功能。
1 MRS 核心 REST API
本節提供在您啟用 REST 後，使用 MySQL REST 服務查詢及其他針對資料表和檢視表的操作範例。
本節中的範例深入了解針對 MySQL REST 服務發出的直接、低階 REST API 呼叫。它們可用於深入了解 MRS 的運作方式。
使用 MRS 開發應用程式時，建議改為使用更高階的 MRS 軟體開發套件 (SDK)。請檢查是否已為您的程式設計語言和平台提供 SDK。
1.1 關於 MRS RESTful Web 服務
MRS 支援建立無限量的不同 RESTful Web 服務。您也可以將它們稱為 MRS 服務。每個 MRS 服務通常對應到一個（或多個）Web 應用程式。
在您建立 RESTful Web 服務後，您可以透過導覽至下列 URL 來存取它。
模式
https://<HOSTNAME:PORT>/<MRS_SERVICE_PATH>/<MRS_DATABASE_SCHEMA_PATH>/<MRS_DATABASE_OBJECT_PATH>/HOSTNAME:PORT/MRS_SERVICE_PATH：指定給定 MRS 服務執行的位址。您也可以將其稱為 MRS 服務 URI。MRS_DATABASE_SCHEMA_PATH：指定您在啟用資料庫綱要的 REST 時提供的路徑。預設情況下，它是綱要的名稱。MRS_DATABASE_OBJECT_PATH：指定您在啟用資料庫物件（TABLE、VIEW 或 PROCEDURE）的 REST 時提供的路徑。
這些值一起構成 MRS 端點 URL。
範例
https://127.0.0.1:8000/mrs/sakila/actor1.2 關於請求路徑語法要求
為防止路徑式攻擊，MRS 要求每個請求 URL 的路徑元素的語法符合下列規則
- 不得為空或僅限空白
- 不得包含下列任何字元：?、#、;、%
- 不得包含 Null 字元 (000)
- 不得包含範圍中的字元：001-031
- 不得以空白或句點 (.) 結尾
- 不得包含雙斜線 (//) 或雙反斜線 (\)
- 不得依序包含兩個或更多句點 (..、… 等)
- 總長度為 {@value #MAX_PATH_LENGTH} 個字元或更少
- 不得比對下列任何名稱 (不區分大小寫)，無論是否含有副檔名：CON、PRN、AUX、CLOCK$、NUL、COM0、COM1、COM2、COM3、COM4、COM5、COM6、COM7、COM8、COM9、LPT0、LPT1、LPT2、LPT3、LPT4、LPT5、LPT6、LPT7、LPT8、LPT9
如果您打算為資料庫物件啟用 REST 端點，則請避免物件名稱不符合這些要求。例如，請勿建立名為 #EMPS 的資料表。如果您想要自動 REST 啟用具有不合規名稱的物件，則必須使用符合要求的別名。
這些要求會套用至 URL 的 URL 解碼形式，以防止嘗試規避百分比編碼。
1.3 關於 cURL 以及測試 RESTful 服務
通常，您可以使用 Web 瀏覽器導覽至 RESTful 服務的 URL。然而，測試它的另一種方式是使用像 cURL 這樣的命令列工具。
cURL 可讓您查看及控制傳送至 RESTful 服務及從其接收的資料。
curl -i https://127.0.0.1:8000/mrs/sakila/actor/2此範例會產生類似以下的響應
{
"links": [
{
"rel": "self",
"href": "https://127.0.0.1:8000/mrs/sakila/actor/2"
}
],
"actor_id": 2,
"last_name": "WAHLBERG",
"first_name": "NICK",
"last_update": "2006-02-15 03:34:33.000000"
}-i 選項會告知 cURL 顯示伺服器傳回的 HTTP 標頭。
2 MRS REST 查詢
MRS REST 服務提供對一個或多個綱要 (及其中繼資料) 以及其包含的資料庫物件（例如資料表、檢視表和程序 (及其的中繼資料)）的存取權。
2.1 取得綱要中繼資料
此範例會擷取透過指定綱要別名提供的資源清單。它會顯示透過啟用資料表、檢視表或程序所建立的 RESTful 服務。
模式
GET http://<HOST>:<PORT>/<ServiceAlias>/<SchemaAlias>/metadata-catalog/範例
GET https://127.0.0.1:8000/mrs/sakila/metadata-catalog/結果
{
"items": [
{
"name": "/actor",
"links": [
{
"rel": "describes",
"href": "https://127.0.0.1:8000/mrs/sakila/actor"
},
{
"rel": "canonical",
"href": "https://127.0.0.1:8000/mrs/sakila/metadata-catalog/actor"
}
]
},
{
"name": "/address",
"links": [
{
"rel": "describes",
"href": "https://127.0.0.1:8000/mrs/sakila/address"
},
{
"rel": "canonical",
"href": "https://127.0.0.1:8000/mrs/sakila/metadata-catalog/address"
}
]
}
],
"limit": 25,
"offset": 0,
"hasMore": false,
"count": 2,
"links": [
{
"rel": "self",
"href": "https://127.0.0.1:8000/mrs/sakila/metadata-catalog/"
}
]
}每個可用的資源都有兩個超連結
- 具有「describes」關係的連結指向實際資源
- 具有「canonical」關係的連結指向資源中繼資料
2.2 取得物件中繼資料
此範例會擷取個別物件的中繼資料（描述物件）。中繼資料的位置由標準連結關係指定。
模式
GET http://<HOST>:<PORT>/<ServiceAlias>/<SchemaAlias>/metadata-catalog/<ObjectAlias>/範例
GET https://127.0.0.1:8000/mrs/sakila/metadata-catalog/actor/結果
{
"name": "/actor",
"primaryKey": [
"actor_id"
],
"members": [
{
"name": "actor_id",
"type": "null"
},
{
"name": "first_name",
"type": "null"
},
{
"name": "last_name",
"type": "null"
},
{
"name": "last_update",
"type": "string"
}
],
"links": [
{
"rel": "collection",
"href": "http://mrs.zinner.org/mrs/sakila/metadata-catalog",
"mediaType": "application/json"
},
{
"rel": "canonical",
"href": "http://mrs.zinner.org/mrs/sakila/metadata-catalog/actor"
},
{
"rel": "describes",
"href": "http://mrs.zinner.org/mrs/sakila/actor"
}
]
}2.3 取得物件資料
此範例會擷取物件中的資料。物件中的每一列都對應到內嵌在 JSON 陣列中的 JSON 物件
模式
GET http://<HOST>:<PORT>/<ServiceAlias>/<SchemaAlias>/<ObjectAlias>/範例
GET https://127.0.0.1:8000/mrs/sakila/actor/結果
{
"items": [
{
"links": [
{
"rel": "self",
"href": "http://mrs.zinner.org/mrs/sakila/actor/1"
}
],
"actor_id": 1,
"last_name": "GUINESSS",
"first_name": "PENELOPE",
"last_update": "2021-09-28 20:18:53.000000"
},
{
"links": [
{
"rel": "self",
"href": "http://mrs.zinner.org/mrs/sakila/actor/2"
}
],
"actor_id": 2,
"last_name": "WAHLBERG",
"first_name": "NICK",
"last_update": "2006-02-15 03:34:33.000000"
},
{
"links": [
{
"rel": "self",
"href": "http://mrs.zinner.org/mrs/sakila/actor/3"
}
],
"actor_id": 3,
"last_name": "CHASE",
"first_name": "ED",
"last_update": "2006-02-15 03:34:33.000000"
},
...
]
}2.3.1 使用分頁取得資料表資料
我們可以指定用於結果資料分頁的 offset 和 limit 參數。
模式
GET http://<HOST>:<PORT>/<ServiceAlias>/<SchemaAlias>/<ObjectAlias>/?offset=<Offset>&limit=<Limit>範例
GET https://127.0.0.1:8080/mrs/sakila/actor/?offset=10&limit=2結果
{
"items": [
{
"links": [
{
"rel": "self",
"href": "http://mrs.zinner.org/mrs/sakila/actor/11"
}
],
"actor_id": 11,
"last_name": "CAGE",
"first_name": "ZERO",
"last_update": "2006-02-15 03:34:33.000000"
},
{
"links": [
{
"rel": "self",
"href": "http://mrs.zinner.org/mrs/sakila/actor/12"
}
],
"actor_id": 12,
"last_name": "BERRY",
"first_name": "KARL",
"last_update": "2006-02-15 03:34:33.000000"
}
],
"limit": 2,
"offset": 10,
"hasMore": true,
"count": 2,
"links": [
{
"rel": "self",
"href": "http://mrs.zinner.org/mrs/sakila/actor/"
},
{
"rel": "next",
"href": "http://mrs.zinner.org/mrs/sakila/actor/?offset=12&limit=2"
},
{
"rel": "prev",
"href": "http://mrs.zinner.org/mrs/sakila/actor/?offset=8&limit=2"
},
{
"rel": "first",
"href": "http://mrs.zinner.org/mrs/sakila/actor/?limit=2"
}
]
}2.3.2 使用查詢取得資料表資料
我們可以使用篩選子句來限制傳回的物件集。
模式
GET http://<HOST>:<PORT>/<ServiceAlias>/<SchemaAlias>/<ObjectAlias>/?q=<FilterClause>範例
GET https://127.0.0.1:8080/mrs/sakila/actor/?q={"last_name":{"$like":"WAW%"}}結果
{
"items": [
{
"links": [
{
"rel": "self",
"href": "http://mrs.zinner.org/mrs/sakila/actor/97"
}
],
"actor_id": 97,
"last_name": "HAWKE",
"first_name": "MEG",
"last_update": "2006-02-15 03:34:33.000000"
}
],
"limit": 25,
"offset": 0,
"hasMore": false,
"count": 1,
"links": [
{
"rel": "self",
"href": "http://mrs.zinner.org/mrs/sakila/actor/"
}
]
}2.3.3 使用主索引鍵取得資料表列
此範例會藉由指定其識別索引鍵值來擷取物件。
注意：資料表需要主索引鍵才能成為 REST 服務的一部分。
模式
GET http://<HOST>:<PORT>/<ServiceAlias>/<SchemaAlias>/<ObjectAlias>/<KeyValues>其中 <KeyValues> 是索引鍵值 (以索引鍵順序) 的逗號分隔清單。
範例
GET https://127.0.0.1:8000/mrs/sakila/actor/53結果
{
"links": [
{
"rel": "self",
"href": "http://mrs.zinner.org/mrs/sakila/actor/53"
}
],
"actor_id": 53,
"last_name": "TEMPLE",
"first_name": "MENA",
"last_update": "2006-02-15 03:34:33.000000"
}2.4 插入資料表列
若要將資料插入資料表，請求內文應為包含要插入之資料的 JSON 物件。
如果物件具有主索引鍵，則 POST 請求可以在內文中包含主索引鍵值。如果資料表具有 AUTO_INCREMENT 資料行，則可以省略主索引鍵資料行。
模式
POST http://<HOST>:<PORT>/<ServiceAlias>/<SchemaAlias>/<ObjectAlias>/範例
curl -i -H "Content-Type: application/json" -X POST -d "{ \"last_name\" : \"FOLEY\", \"first_name\": \"MIKE\" }" "https://127.0.0.1:8000/mrs/sakila/actor/" Content-Type: application/json結果
{
"links": [
{
"rel": "self",
"href": "https://127.0.0.1:8000/mrs/sakila/actor/201"
}
],
"actor_id": 201,
"last_name": "FOLEY",
"first_name": "MIKE",
"last_update": "2022-11-29 15:35:17.000000"
}2.5 更新/插入資料表列
若要將資料插入、更新或「插入更新」(如果存在則更新，否則插入) 至資料表，我們可以傳送請求，其中內文包含 JSON 物件，其中包含要插入或更新的資料。
模式
PUT http://<HOST>:<PORT>/<ServiceAlias>/<SchemaAlias>/<ObjectAlias>/<KeyValues>範例
curl -i -H "Content-Type: application/json" -X PUT -d "{ \"last_name\" : \"FOLEY\", \"first_name\": \"JACK\" }" "https://127.0.0.1:8000/mrs/sakila/actor/201" Content-Type: application/json結果
{
"links": [
{
"rel": "self",
"href": "http://mrs.zinner.org/mrs/sakila/actor/201"
}
],
"actor_id": 201,
"last_name": "FOLEY",
"first_name": "JACK",
"last_update": "2022-11-29 15:45:10.000000"
}2.6 使用篩選條件刪除
刪除物件或其他資料庫物件可以透過指定識別要刪除之物件的篩選子句來完成。
模式
DELETE http://<HOST>:<PORT>/<ServiceAlias>/<SchemaAlias>/<ObjectAlias>/?q=<FilterClause>範例
curl -i -X DELETE "https://127.0.0.1:8000/mrs/sakila/actor/?q=\{\"actor_id\":201\}"結果
{
"itemsDeleted": 1
}3 FilterObject 語法
FilterObject 必須是符合下列語法的 JSON 物件
FilterObject { orderby , asof, wmembers }orderby、asof 和 wmembers 屬性是選用的，其定義如下
orderby
"$orderby": {orderByMembers}
orderByMembers
orderByProperty
orderByProperty , orderByMembers
orderByProperty
columnName : sortingValue
sortingValue
"ASC"
"DESC"
"-1"
"1"
-1
1
asof
"$asof": date
"$asof": "datechars"
"$asof": scn
"$asof": +int
wmembers
wpair
wpair , wmembers
wpair
columnProperty
complexOperatorProperty
columnProperty
columnName : string
columnName : number
columnName : date
columnName : simpleOperatorObject
columnName : complexOperatorObject
columnName : [complexValues]
columnName
"\p{Alpha}[[\p{Alpha}]]([[\p{Alnum}]#$_])*$"
complexOperatorProperty
complexKey : [complexValues]
complexKey : simpleOperatorObject
complexKey
"$and"
"$or"
complexValues
complexValue , complexValues
complexValue
simpleOperatorObject
complexOperatorObject
columnObject
columnObject
{columnProperty}
simpleOperatorObject
{simpleOperatorProperty}
complexOperatorObject
{complexOperatorProperty}
simpleOperatorProperty
"$eq" : string | number | date
"$ne" : string | number | date
"$lt" : number | date
"$lte" : number | date
"$gt" : number | date
"$gte" : number | date
"$instr" : string
"$ninstr" : string
"$like" : string
"$null" : null
"$notnull" : null
"$between" : betweenValue
"$like": string
betweenValue
[null , betweenNotNull]
[betweenNotNull , null]
[betweenRegular , betweenRegular]
betweenNotNull
number
date
betweenRegular
string
number
date資料類型定義包括下列內容
string
JSONString
number
JSONNumber
date
{"$date":"datechars"}
scn
{"$scn": +int}其中
datechars is an RFC3339 date format in UTC (Z)
JSONString
""
" chars "
chars
char
char chars
char
any-Unicode-character except-"-or-\-or-control-character
\"
\\
\/
\b
\f
\n
\r
\t
\u four-hex-digits
JSONNumber
int
int frac
int exp
int frac exp
int
digit
digit1-9 digits
- digit
- digit1-9 digits
frac
. digits
exp
e digits
digits
digit
digit digits
e
e
e+
e-
E
E+
E-必須根據 RFC3986 的第 2.1 節編碼 FilterObject。
4 FilterObject 語法範例
4.1 ORDER BY 屬性 ($orderby)
Order by with literals
{
"$orderby": {"SALARY": "ASC","ENAME":"DESC"}
}
Order by with numbers
{
"$orderby": {"SALARY": -1,"ENAME": 1}
}4.2 ASOF 屬性 ($asof)
With SCN (Implicit)
{
"$asof": 1273919
}
With SCN (Explicit)
{
"$asof": {"$scn": "1273919"}
}
With Date (Implicit)
{
"$asof": "2014-06-30T00:00:00Z"
}
With Date (Explicit)
{
"$asof": {"$date": "2014-06-30T00:00:00Z"}
}4.3 等於運算子 ($eq)
Implicit (Support String and Dates too)
{
"SALARY": 1000
}
Explicit
{
"SALARY": {"$eq": 1000}
}
Strings
{
"ENAME": {"$eq":"SMITH"}
}
Dates
{
"HIREDATE": {"$date": "1981-11-17T08:00:00Z"}
}4.4 不等於運算子 ($ne)
Number
{
"SALARY": {"$ne": 1000}
}
String
{
"ENAME": {"$ne":"SMITH"}
}
Dates
{
"HIREDATE": {"$ne": {"$date":"1981-11-17T08:00:00Z"}}
}4.5 小於運算子 ($lt)
(僅支援日期和數字)
Numbers
{
"SALARY": {"$lt": 10000}
}
Dates
{
"SALARY": {"$lt": {"$date":"1999-12-17T08:00:00Z"}}
}4.6 小於或等於運算子 ($lte)
(僅支援日期和數字)
Numbers
{
"SALARY": {"$lte": 10000}
}
Dates
{
"HIREDATE": {"$lte": {"$date":"1999-12-17T08:00:00Z"}}
}4.7 大於運算子 ($gt)
(僅支援日期和數字)
Numbers
{
"SALARY": {"$gt": 10000}
}
Dates
{
"SALARY": {"$gt": {"$date":"1999-12-17T08:00:00Z"}}
}4.8 大於或等於運算子 ($gte)
(僅支援日期和數字)
Numbers
{
"SALARY": {"$gte": 10000}
}
Dates
{
"HIREDATE": {"$gte": {"$date":"1999-12-17T08:00:00Z"}}
}4.9 字串中包含運算子 ($instr)
(僅支援字串)
{
"ENAME": {"$instr":"MC"}
}4.10 字串中不包含運算子 ($ninstr)
(僅支援字串)
{
"ENAME": {"$ninstr":"MC"}
}4.11 LIKE 運算子 ($like)
(支援字串。不支援逸出字元以嘗試比對具有 _ 或 % 字元的運算式。)
{
"ENAME": {"$like":"AX%"}
}4.12 BETWEEN 運算子 ($between)
(支援字串、日期和數字)
Numbers
{
"SALARY": {"$between": [1000,2000]}
}
Dates
{
"SALARY": {"$between": [{"$date":"1989-12-17T08:00:00Z"},{"$date":"1999-12-17T08:00:00Z"}]}
}
Strings
{
"ENAME": {"$between": ["A","C"]}
}
Null Ranges ($lte equivalent)
(Supported by numbers and dates only)
{
"SALARY": {"$between": [null,2000]}
}
Null Ranges ($gte equivalent)
(Supported by numbers and dates only)
{
"SALARY": {"$between": [1000,null]}
}4.13 NULL 運算子 ($null)
{
"ENAME": {"$null": null}
}4.14 NOT NULL 運算子 ($notnull)
{
"ENAME": {"$notnull": null}
}4.15 AND 運算子 ($and)
(支援所有運算子，包括 $and 和 $or)
Column context delegation
(Operators inside $and will use the closest context defined in the JSON tree.)
{
"SALARY": {"$and": [{"$gt": 1000},{"$lt":4000}]}
}
Column context override
(Example: salary greater than 1000 and name like S%)
{
"SALARY": {"$and": [{"$gt": 1000},{"ENAME": {"$like":"S%"}} ] }
}
Implicit and in columns
{
"SALARY": [{"$gt": 1000},{"$lt":4000}]
}4.16 高階 AND
(所有第一資料行和/或在高階運算子 – $and 和 $ors – 在 JSON 的第一層定義會聯結，以及隱含的 AND)
(Example: Salary greater than 1000 and name starts with S or T)
{
"SALARY": {"$gt": 1000},
"ENAME": {"$or": [{"$like":"S%"}, {"$like":"T%"}]}
}
Invalid expression (operators $lt and $gt lack column context)
{
"$and": [{"$lt": 5000},{"$gt": 1000}]
}
Valid alternatives for the previous invalid expression
{
"$and": [{"SALARY": {"$lt": 5000}}, {"SALARY": {"$gt": 1000}}]
}
{
"SALARY": [{"$lt": 5000},{"$gt": 1000}]
}
{
"SALARY": {"$and": [{"$lt": 5000},{"$gt": 1000}]}
}4.17 OR 運算子 ($or)
(支援所有運算子，包括 $and 和 $or)
Column context delegation
(Operators inside $or will use the closest context defined in the JSON tree)
{
"ENAME": {"$or": [{"$eq":"SMITH"},{"$eq":"KING"}]}
}
Column context override
(Example: name starts with S or salary greater than 1000)
{
"SALARY": {"$or": [{"$gt": 1000},{"ENAME": {"$like":"S%"}} ] }
}版權所有 (c) 2022、2023 Oracle 和/或其關係企業。