文章彙整

Magento2 開發 – 如何使用API的搜尋條件 “searchCriteria”

Astral WebBy Astral Web 3 months agoNo Comments
首頁  /  Magento  /  Magento-2  /  Magento2 開發 – 如何使用API的搜尋條件 “searchCriteria”

我們在客製Magento時,多少會遇到需要與其他系統串接的需求。也許是Magento作為主動方去要資料,也可能為被動方被呼叫。而Magento本身已有提供restful API,點擊以下的官方連結,可以查看API所提供的功能
https://devdocs.magento.com/swagger/index_23.html

這些API的使用方式,文件上都有基本說明,像是功能端點(endpoint)、HTTP方法(method),以及傳送的參數與回應格式。這當中仍需要開發者再花時間探究的,筆者認為當屬 “搜尋參數-searchCriteria”。瀏覽一下文件中屬於列表類的端點,像是產品列表 [ GET /V1/products ],產品分類列表 [ GET /V1/categories/list ],訂單列表 [ GET /V1/orders ]……等,會看到有個通用參數 searchCriteria,關於這個參數,文件給出的說明如下

Page size.(分頁筆數) 跟 Current page.(目前頁次) 算是好理解,其他的 Field, Value, Condition type, Sorting field, Sroting direction 卻無法一看就知道如何丟值,今天就要帶大家了解這個參數怎麼使用。

我們先從最複雜的Field, Value, Condition type 組合開始。為什麼說是組合呢?因為這三個值是並存的。他們闡述著什麼欄位(Field)要以什麼方式(Condition type)去跟什麼值(Value)做比較。舉例來說,要查詢訂單號碼等於1000000條件時,代表 Field=訂單號碼(increment_id),Condition type=等於(eq),Value=1000000。只是searchCriteria要求的格式更為複雜:

searchCriteria[filterGroups][0][filters][0][field]
searchCriteria[filterGroups][0][filters][0][value]
searchCriteria[filterGroups][0][filters][0][conditionType]

注意囉!這裡filterGroups , filters跟數字0的意思分別為

  1. 數字0是陣列中的序列,表示可以多個子值,0為第一個
  2. 若條件群組放在filterGroups下,表示必須都符合
  3. 若條件群組放在filters下,則是表示符合其一即可

舉例來說,要查詢訂單編號是1000000或1000001,條件群組為

群組一
Field=訂單號碼
Condition type=等於
Value=1000000

群組二
Field=訂單號碼
Condition type=等於
Value=1000001

群組一或二符合其一即可,其條件表示的JSON結構為

searchCriteria = {
    “fitlerGroups”: {
        “filters”: [
            {
                “field”: “increment_id”,
                “value”: “1000000”,
                “conditionType”: “eq”
            },
            {
                “field”: “increment_id”,
                “value”: “1000001”,
                “conditionType”: “eq”
            }
        ]
    }
}

轉換成實際參數就是

searchCriteria[filterGroups][0][filters][0][field] = ‘increment_id’
searchCriteria[filterGroups][0][filters][0][value] = ‘1000000’
searchCriteria[filterGroups][0][filters][0][conditionType] = ‘eq’
searchCriteria[filterGroups][0][filters][1][field] = ‘increment_id’
searchCriteria[filterGroups][0][filters][1][value] = ‘1000001’
searchCriteria[filterGroups][0][filters][1][conditionType] = ‘eq’

而要查詢訂單編號介於 1000000 與 1000500間,條件群組為

群組一
Field=訂單號碼
Condition type=大於等於
Value=1000000

群組二
Field=訂單號碼
Condition type=小於等於
Value=1000500

群組一跟二都要符合,條件表示的JSON結構則是

searchCriteria = {
    “filterGroups”: [
         {
             “filters”: [
                  “field”: “increment_id”,
                  “value”: “1000000”,
                  “conditionType”: “gteq”
              ]
         },
         {
             “filters”: [
                  “field”: “increment_id”,
                  “value”: “1000500”,
                  “conditionType”: “lteq”
              ]
         }
    ]
}

轉換成實際參數為

searchCriteria[filterGroups][0][filters][0][field] = ‘increment_id’
searchCriteria[filterGroups][0][filters][0][value] = ‘1000000’
searchCriteria[filterGroups][0][filters][0][conditionType] = ‘gteq’
searchCriteria[filterGroups][1][filters][0][field] = ‘increment_id’
searchCriteria[filterGroups][1][filters][0][value] = ‘1000500’
searchCriteria[filterGroups][1][filters][0][conditionType] = ‘lteq’

清楚了『且』與『或』的差異,再加上條件群組的設定結構,就能組合出需要的條件參數囉!

接下來的Sorting field(排序欄位)跟Sorting direction(排序方式)就簡單多了,這是兩兩成對的參數

searchCriteria[sortOrders][0][field]
searchCriteria[sortOrders][0][direction]

這裡的數字0可以參照條件群組的應用去理解,也就是可以多個欄位去排序

假設我們希望查詢的結果,先以訂單金額由大到小排列,遇到同金額時,再以訂單編號由小到大排列,那麼JSON結構就是

searchCriteria = {
    “sortOrders”: [
        {
            “field”: “base_grand_total”,
             “direction”: “desc”
        },
        {
            “field”: “increment_id”,
             “direction”: “asc”
        }
    ]
}

轉換為實際參數

searchCriteria[sortOrders][0][field] = ‘base_grand_total’
searchCriteria[sortOrders][0][direction] = ‘desc’
searchCriteria[sortOrders][1][field] = ‘increment_id’
searchCriteria[sortOrders][1][direction] = ‘asc’

到這裡我們已經了解了searchCriteria所有子參數的使用方式。有了以上這些關鍵範例,相信下次諸位要使用API去搜尋資料時,就不必再多花時間研究該如何寫出符合需求的條件參數囉!

最後再提醒一下,雖然searchCriteria的格式設計,可以讓使用者自由的下多個條件,但因為這個參數是帶在網址上,而網址有長度上限,因此使用上仍然要注意控制,不可以讓所有條件產出的網址長度超過限制唷。那麼我們下次見!

若想接收最新的文章資訊,請務必訂閱我們的電子報,以及追蹤我們的臉書粉絲團Instagram,才能收到第一手的最新資訊喔!

想學習更多Magento設定嗎?請見:Magento教學導覽

以上內容由Astralweb 歐斯瑞編寫製作

 000

推薦文章

Categories:
  Magento-2MagentoMagento開發

留下回應

你的電子郵件地址不會被公開.

取得獨家電子商務祕技

建立更好的策略靈感

跟上全球的網路趨勢

絕佳的電商解決方案

電子商務戰略全指南

每月發送電商戰略指南,只要填寫E-mail即可訂閱!

請到您的信箱確認,即可完成訂閱。