---
# System prepended metadata

title: API 功能介紹

---

## 新增表格紀錄

### 查詢

```graphql=
mutation insert($table: String!, $data: [InsertRecord!]!) {
  insert(table: $table, data: $data)
}
```

### 參數

| 參數名稱 | 是否必填 | 備註 |
| ------- | ------ | ---- |
| table | 是 | 表格名稱 |
| data | 是 | 要新增的紀錄，支援批次新增。|

### 回傳值

新增紀錄後將回應一個數值陣列，內容是被新增紀錄的 id 值

### 範例

查詢: 新增一個會員

```graphql=
mutation insert($table: String!, $data: [InsertRecord!]!) {
  insert(table: $table, data: $data)
}
```

參數 (Variables 的形式)

```json=
{
  "table": "member",
  "data": [
    {
      "bodyFields": [
        {
          "fieldName": "username",
          "valueType": "STRING",
          "string": "Mary"
        },
        {
          "fieldName": "age",
          "valueType": "NUMBER",
          "number": 33
        }
      ],
      "lineRows": []
    }
  ]
}
```

結果

```json=
{
    "data": {
        "mutationResult": [14]
    }
}
```

## 更新表格紀錄

### 查詢

```graphql=
mutation update($table: String!, $data: [UpdateRecord!]!) {
  update(table: $table, data: $data)
}
```

### 參數

| 參數名稱  | 是否必填 | 備註    |
| ------- | --------  | ------- |
|  table  | 是       | 表格名稱 |
|  data   | 是       | 要更新的紀錄，支援批次更新。|

### 回傳值

更新紀錄後將回應一個數值陣列，內容是被更新紀錄的 id 值

### 範例

查詢: 更新一個會員

```graphql=
mutation update($table: String!, $data: [UpdateRecord!]!) {
  update(table: $table, data: $data)
}
```

參數 (Variables 的形式)

```json=
{
  "table": "member",
  "data": [
    {
      "keyName": "username",
      "keyValue": "Mary",
      "bodyFields": [
        {
          "fieldName": "age",
          "valueType": "NUMBER",
          "number": 23
        }
      ]
    }
  ]
}
```

結果

```json=
{
    "data": {
        "mutationResult": [14]
    }
}
```

## 查詢表格紀錄

查詢表格紀錄，可以篩選需要的資料。

### 查詢

```graphql=
query ($offset: Int, $limit: Int, $sorting: FindSorting, $filters: [FindFilter!]) {
  findSomeTable(offset: $offset, limit: $limit, sorting: $sorting, filters: $filters) {
    body { field1 field2 }
  }
}
```

端點名稱使用的固定格式是 `findXXX` 其中 XXX 是表格的英文名稱，並且首字大寫。例如一個表格名稱為 `posmember` ，查詢的名稱就是 `findPosmember`

### 參數

|  參數名稱  | 是否必填 | 備註    |
|  -------  | ------ | ------- |
|  filters  |        | 設定一些篩選的條件<br>1. 可以傳入複數個篩選器，篩選器之間的關係為 **聯集（or）**<br>2. 篩選器條件與條件間關係為 **交集（and）**<br>3. 部分條件可以輸入多個查詢值，此時查詢值之間的關係為 **聯集（or）** |
|  sorting  |        | 將紀錄以某個欄位做排序。1 代表升冪排序；-1 代表降冪排序 |
|  limit    |        | 限制回傳紀錄的數量。預設是 100 筆 |
|  offset   |        | 頁偏移量，通常使用在分頁，依據當前使用的 limit 做分頁偏移。<br>limit=50, offset=0 相當於取得第 1 ~ 50 筆資<br>limit=50, offset=1 相當於取得第 51 ~ 100 筆資料<br>以此類推 |

#### 篩選範例 1
查詢會員姓名為 `使用者` 且 手機號碼為 `+886987654321` 或 `+886900000000`的會員資料
```json=
{
    "filters": [
        {
            "bodyConditions": [
                {
                    "fieldName": "displayName",
                    "valueType": "STRING",
                    "string": "使用者",
                    "operator": "in"
                },
                {
                    "fieldName": "mobile",
                    "valueType": "STRING",
                    "string": "+886987654321",
                    "operator": "in"
                },
                {
                    "fieldName": "mobile",
                    "valueType": "STRING",
                    "string": "+886900000000",
                    "operator": "in"
                },
            ]
        }
    ],
}
```
#### 篩選範例 2
查詢符合以下條件的會員
1. 手機號碼為 `+886987654321` 且 會員姓名為 `使用者1`
2. 手機號碼為`+886900000000` 且 會員姓名為 `使用者2`
```json=
{
    "filters": [
        // 第一組 filter
        {
            "bodyConditions": [
                {
                    "fieldName": "mobile",
                    "valueType": "STRING",
                    "string": "+886987654321",
                    "operator": "in"
                },
                {
                    "fieldName": "displayName",
                    "valueType": "STRING",
                    "string": "使用者1",
                    "operator": "in"
                },
            ]
        },
        // 第二組 filter
        {
            "bodyConditions": [
                {
                    "fieldName": "mobile",
                    "valueType": "STRING",
                    "string": "+886900000000",
                    "operator": "in"
                },
                {
                    "fieldName": "displayName",
                    "valueType": "STRING",
                    "string": "使用者2",
                    "operator": "in"
                },
            ]
        },
    ],
}
```

### 回傳值

更新紀錄後將回應一個數值陣列，內容是被更新紀錄的 id 值

### 範例

查詢: 找出大於等於 20 歲的會員，只取前十筆，以會員名稱倒序輸出

```graphql
query ($offset: Int, $limit: Int, $sorting: FindSorting, $filters: [FindFilter!]) {
    findPosMember(offset: $offset, limit: $limit, sorting: $sorting, filters: $filters) {
        body {
            username
            age
        }
    }
}
```

參數 (Variables 的形式)

```json=
{
    "offset": 0,
    "limit":  10,
    "sorting": {
        "field": "body.username",
        "direction": -1
    },
    "filters": [
        {
            "bodyConditions": [
                {
                    "fieldName": "age",
                    "valueType": "NUMBER",
                    "number": 20,
                    "operator": "gte"
                }
            ]
        }
    ]
}
```

結果

```json=
{
    "data": {
        "findPosmember": [
            {
                "body": {
                    "username": "Zypher",
                    "age": 21
                }
            },
            {
                "body": {
                    "username": "James",
                    "age": 23
                }
            },
        ]
    }
}
```

## 呼叫表格函數

每個表格可能有一些已預先定義好的動作，稱為表格函數，透過執行 call 可以執行這些動作。

### 查詢

```graphql=
mutation call($table: String!, $name: String!, $argument: String!) {
    call(table: $table, name: $name, argument: $argument)
}
```

### 參數

| 參數名稱  | 是否必填 | 備註    |
| ------- | --------  | ------- |
|  table  | 是       | 表格名稱 |
|  name   | 是       | 表格函數名稱 |
|  argument   | 是       | 函數的引數，內容依照各表格定義。JSON strinify 後傳入 |

### 回傳值

呼叫後將回傳一個字串，內容依照各表格定義

### 範例

查詢: 計算會員幸運數

```graphql
mutation call($table: String!, $name: String!, $argument: String!) {
	call(table: $table, name: $name, argument: $argument)
}
```

參數 (Variables 的形式)

```json=
{
  "table": "member",
  "name": "計算幸運數",
  "argument": "{\"username\":\"John\"}}"
}
```

結果

```json=
{
    "data": {
        "call": "{\"body\":{\"luckyNumber\": 7}}"
    }
}
```

## API 串接測試

僅提供測試串接使用，相關欄位與函式不具有特殊意義

### 表格欄位範例

-   測試表格名: magentotest
-   表頭與表身欄位 (findMagentotest)

|  表頭欄位名稱  | 中文名稱 |             數值類型            | 新增屬性 | 更新屬性 |
| ------------ | ------- | ----------------------------- | -------- | -------- |
| name         | 會員編號 | 字串                           | N        | R        |
| displayName  | 會員姓名 | 字串                           | R        | I        |
| email        | 電子郵件 | 字串(可能為空值)                 | O        | U        |
| gender       | 性別     | 字串列舉值 `MALE,FEMALE,OTHERS` | R        | U        |
| birth        | 生日     | 日期，ISO 字串格式              | R        | U        |
| height       | 身高     | 浮點數                         | O        | U        |
| age          | 年齡     | 整數                           | O        | U        |
| isNative     | 本國人   | 布林值                         | O        | U        |

| 表身 | 中文名稱 | 表身資料屬性 |
| ---- | -------- | ------------ |
| tag  | 標籤     | F            |

| 所屬表身 | 表身欄位 | 中文名稱 | 數值類型 | 新增屬性 | 更新屬性 |
| -------- | -------- | -------- | -------- | -------- | -------- |
| tag      | text     | 標籤文字 | 字串     | R        | I        |

-   客製化函式

| 所屬表格    | 函式名稱 | 輸入參數          | 回傳值 |
| ----------- | -------- | ----------------- | ------ |
| magentotest | 領取獎勵 | 見 `領取獎勵參數` | 字串   |

註：回傳值一律為 JSON 字串，必須經過轉換才能取得真正的回傳值

`領取獎勵參數`:

```JSON=
{
    "body": {
        "customArg": "王小明"
    },
    "lines": {
        "tags": [{
            "text": "標籤"
        }]
    }
}
```

### 表格欄位與表身屬性說明

-   欄位新增屬性

    -   N = 無須填寫
    -   R = 必填
    -   O = 選填

-   更新欄位屬性

    -   R = 唯讀，無法修改
    -   I = 新增後無法更新
    -   U = 可更新

-   表身資料屬性

    -   F = 可隨意更新指定表身資料
    -   R = 僅能讀取指定表身資料，無法新增、更新、刪除
    -   U = 僅可對指定表身已存在的資料做更新，無法新增、刪除
    -   P = 可對指定表身資料新增、更新，無法刪除
    -   D = 僅可對指定表身資料做刪除
    -   I = 只有在建立資料時可設定表身資料，建立後無法新增、更新、刪除

    | 表身屬性 | 讀取 | 初始建立 | 新增 | 移除 | 更新 |
    | -------- | ---- | -------- | ---- | ---- | ---- |
    | F        | O    | O        | O    | O    | O    |
    | R        | O    | X        | X    | X    | X    |
    | U        | O    | O        | X    | X    | O    |
    | P        | O    | O        | O    | X    | O    |
    | D        | O    | O        | X    | O    | X    |
    | I        | O    | O        | X    | X    | X    |
