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

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

我們在客製Magento時，多少會遇到需要與其他系統串接的需求。也許是Ｍagento作為主動方去要資料，也可能為被動方被呼叫。而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的意思分別為

數字0是陣列中的序列，表示可以多個子值，0為第一個
若條件群組放在filterGroups下，表示必須都符合
若條件群組放在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所有子參數的使用方式。有了以上這些關鍵範例，相信下次諸位要使用ＡＰＩ去搜尋資料時，就不必再多花時間研究該如何寫出符合需求的條件參數囉！

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

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

想學習更多Magento設定嗎？請見：Magento教學導覽

Magento, 技術應用

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