登入 / 註冊

應用程式介面指南


你的應用程式介面金鑰

這是你的應用程式介面金鑰（API Token），用來調用應用程式介面。請勿將金鑰告知其他人，或儲存在公開的GitHub儲存庫。

應用程式介面金鑰

M+應用程式介面端點

這是GraphQL端點，你會透過它調用應用程式介面。更多進行調用的詳情，可參見下方。

M+應用程式介面端點
https://api.mplus.org.hk/graphql

如何使用M+應用程式介面

M+應用程式介面用了GraphQL這個開源數據查詢語言，你將使用GraphQL取得M+數據庫內的資料。

一般來說，GraphQL有兩種操作方式：查詢（queries）及變更（mutations），可理解為讀取（read）和寫入（write）。另外還有一項名為「內省」的操作，讓你向GraphQL端點進行詢問

與M+應用程式介面Playground調試工具

這是試驗GraphQL查詢最簡易的方法，可於以下連結進入：
https://api.mplus.org.hk//playground

按下「運行Playground調試工具」的連結後，就可看到例子。只要按下「運行」按鈕，就能看到查詢結果。
運行playground調試工具

如何與M+應用程式介面交流

你可在此找到調用GraphQL端點的不同例子。所有調用應用程式介面的唯一端點是：

https://api.mplus.org.hk/graphql

GraphQL的操作由擁有多行字符串的JSON格式組成，以「Hello World」（你好，世界）為例，它的GraphQL查詢如下：

運行playground調試工具 

query {
  hello
}

如使用cURL命令來查詢GraphQL，請以帶有--data-binary（二進制數據）的有效載荷JSON格式發送POST請求。你必須同時包括你的應用程式介面金鑰，作為bearer（持有人）認證。 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  hello \
}\"}" \
https://api.mplus.org.hk/graphql

以下是採用Nodejs的情況，請確定你已輸入應用程式介面金鑰，作為 bearer（持有人）認證 

const request = require('request')

const payload = {
  query: `{
    hello
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)

M+應用程式介面查詢

以下是一系列現時可向M+應用程式介面進行的查詢。

內省

內省（Introspection）是唯一可以採用GET（取得）來調用的操作。內省讓你查詢GraphQL schema，得知有關它的細節。查詢__schema 時，會得到所有schema的類型，以及每個類型的細節：

運行playground調試工具 

query {
  __schema {
    types {
      description
      fields {
        args {
          name
          type {
            name
          }
          defaultValue
        }
        description
        name
        type {
          name
        }
      }
      kind
      name
    }
  }
}

篩選查詢

你可以數個方式篩選M+應用程式介面，有效的篩選為：page（頁數）、per_page（每頁結果）、lang（語言）、sort（排序）及sort_field（字段排序）。sort_field 的有效值為 title（標題）和 count（數目）。sort（排序）的有效值為 asc（遞增）和 desc（遞減）。

以per_page（每頁結果）篩選可限制查詢結果的數目。舉個例說，輸入 (per_page: 10)的話，就只會回傳10項紀錄。與查詢物件不同，此數據集不能分頁。

若各項查詢有更多的方式篩選，或有更多有效值，將於下方相應部分指出。

物件

物件所指的是M+藏品系列中各件藝術品、流動影像及其他作品。

這項查詢會選擇所有物件，並能夠透過以下字段進行篩選。備註：篩選屬累加性質而非任擇其一，篩選兩個字段的話，只會回傳同時吻合兩者的數據。

有效的篩選器為：page（頁數）、per_page（每頁結果）、[ids]、lang（語言）、sort（排序）、sort_field（字段排序）、 objectNumber（物件號碼）、 area（範圍）、category（分類）、 archivalLevel（檔案層次）、collectionName（藏品名稱）、collectionCode（藏品號碼）、collectionType（藏品類型）、 medium（媒材）、 title（標題）、displayDate（展示日期）、beginDate（開始日期）、endDate（結束日期）、constituent（相關各方）、[constituents], exhibition（展覽）及keyword（關鍵字）。

備註：篩選器collectionName（藏品名稱）、collectionCode（藏品號碼）、collectionType（藏品類型）用於查詢檔案藏品的資料，有助分辨來自檔案藏品的結果。

sort_field（字段排序）的有效值為 id、objectNumber（物件號碼）、sortNumber（排序號碼）、title（標題）、displayDate（展示日期）、beginDate（開始日期）、endDate（結束日期）、popularCount（瀏覽量）、area（範圍）、medium（媒材）、archivalLevel（檔案層次）和category（類別）。sort（排序）的有效值為 asc（遞增）和 desc（遞減）。

lang（語言）的有效值只有 en（英文）和zh-hant（繁體中文）。預設語言為 en，如果資料庫沒有符合所選語言的有效值，便會回傳 en版本（如有）

以下是調用所有物件最簡單的方法

運行playground調試工具 

query {
  objects {
    id
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  objects { \
    id \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    objects {
      id
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
透過id取得

你亦可以透過輸入一系列ids，查詢特定的物件。

運行playground調試工具 

query {
  objects(ids:[1, 4, 6, 7]) {
    id
    objectNumber
    title
    displayDate
    medium
    classification {
      area
      category
    }
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  objects(ids:[1, 4, 6, 7]) { \
    id \
    objectNumber \
    title \
    displayDate \
    medium \
    classification { \
      area \
      category \
    } \
  } \
}\"}" \
https://api.mplus.org.hk/graphql
查詢個別物件

你可以透過輸入id參數，獲得單一物件。以下是所有可顯示的字段。

運行playground調試工具 

query {
  object(id: 3000) {
    id
    sortNumber
    publicAccess
    objectNumber
    classification {
      area
      category
      archivalLevel
    }
    title
    titleOther
    displayDate
    displayDateOther
    beginDate
    endDate
    dimension
    dimensionDetails {
      width
      height
      depth
      unit
      element
      rank
    }
    medium
    creditLine
    constituents {
      id
      name
    }
    images {
      altText
    }
    color {
      predominant {
        color
        value
      }
      search {
        google {
          color
          value
        }
        cloudinary {
          color
          value
        }
      }
    }
    
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  object(id: 3000) { \
    id \
    sortNumber \
    publicAccess \
    objectNumber \
    classification { \
      area \
      category \
      archivalLevel \
    } \
    title \
    titleOther \
    displayDate \
    displayDateOther \
    beginDate \
    endDate \
    dimension \
    dimensionDetails { \
      width \
      height \
      depth \
      unit \
      element \
      rank \
    } \
    medium \
    creditLine \
    constituents { \
      id \
      name \
    } \
    images { \
      altText \
    } \
    color { \
      predominant { \
        color \
        value \
      } \
      search { \
        google { \
          color \
          value \
        } \
        cloudinary { \
          color \
          value \
        } \
      } \
    } \
     \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    object(id: 3000) {
      id
      sortNumber
      publicAccess
      objectNumber
      classification {
        area
        category
        archivalLevel
      }
      title
      titleOther
      displayDate
      displayDateOther
      beginDate
      endDate
      dimension
      dimensionDetails {
        width
        height
        depth
        unit
        element
        rank
      }
      medium
      creditLine
      constituents {
        id
        name
      }
      images {
        altText
      }
      color {
        predominant {
          color
          value
        }
        search {
          google {
            color
            value
          }
          cloudinary {
            color
            value
          }
        }
      }
      
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
分頁和篩選例子

以下我們稍為增加查詢資訊量，請留意我們如何以per_page（每頁結果）篩選器，以限制每頁查詢結果的數目。

運行playground調試工具 

query {
  objects(page:0, per_page: 5, area: "Moving Image") {
    id
    objectNumber
    title
    displayDate
    medium
    classification {
      area
      category
    }
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  objects(page:0, per_page: 5, area: \\\"Moving Image\\\") { \
    id \
    objectNumber \
    title \
    displayDate \
    medium \
    classification { \
      area \
      category \
    } \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    objects(page:0, per_page: 5, area: "Moving Image") {
      id
      objectNumber
      title
      displayDate
      medium
      classification {
        area
        category
      }
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
排序

以下是使用 sortNumber（排序號碼）進行排序的例子。

運行playground調試工具 

query {
  objects(sort_field: "sortNumber", sort: "asc") {
    id
    publicAccess
    objectNumber
    sortNumber
    title
    displayDate
    beginDate
    endDate
    dimension
    creditLine
    medium
    classification {
      area
      category
    }
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  objects(sort_field: \\\"sortNumber\\\", sort: \\\"asc\\\") { \
    id \
    publicAccess \
    objectNumber \
    sortNumber \
    title \
    displayDate \
    beginDate \
    endDate \
    dimension \
    creditLine \
    medium \
    classification { \
      area \
      category \
    } \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    objects(sort_field: "sortNumber", sort: "asc") {
      id
      publicAccess
      objectNumber
      sortNumber
      title
      displayDate
      beginDate
      endDate
      dimension
      creditLine
      medium
      classification {
        area
        category
      }
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
以顏色篩選或搜尋

若果想以顏色搜尋物件，你可用下列篩選字詞：color（顏色）、color_threshold（顏色臨界值）和color_source（顏色來源）。

顏色來源總共有兩個：google 及 cloudinary。預設的顏色來源為Google，以下為可選的顏色：gray（灰）、black（黑）、orange（橙）、brown（棕）、white（白）、yellow（黃）、teal（藍綠色）、blue（藍）、green（綠）、red（紅）、pink（粉紅）及purple（紫）。

Cloudinary提供的顏色則稍為不同，包括一些較具體的顏色，例如：gray（灰）、black（黑）、orange（橙）、brown（棕）、white（白）、yellow（黃）、teal（藍綠色）、blue（藍）、green（綠）、red（紅）、pink（粉紅）、purple（紫）、lightblue（淺藍）、olive（橄欖綠）、lime（青檸）及cyan（青）。如果你想以這些顏色搜尋，請將 color_source（顏色來源）設為cloudinary。

Color_threshold（顏色臨界值）讓你設定每種顏色的範圍。顏色臨界值的預設數值為75.0，如你想設定不同的數值，可在0.0至100.0內選擇。臨界值愈高，搜尋結果則愈少。（臨界值愈高，某種特定顏色在圖片中佔的比率就愈高。）

你亦可詢問結果中的predominant（主要）顏色，取得主要顏色的HEX顏色值。請見以下例子。

運行playground調試工具 

query {
  objects(color: "orange", color_threshold: 70.0, color_source: "google") {
    id
    title
    color {
      predominant {
        color
        value
      }
      search {
        google {
          color
          value
        }
        cloudinary {
          color
          value
        }
      }
    }
  }
}

範圍

「範圍」指的是物件所屬的某個領域或更廣泛的類別，例如視覺藝術、流動影像或設計及建築。要取得所有範圍，你可使用以下方法查詢：

有效的篩選器為 page（頁數）、per_page（每頁結果）、lang（語言）、sort（排序）和 sort_field（字段排序）。sort（排序）的有效值為 asc（遞增）和 desc（遞減）。 sort_field（字段排序）的有效值為 title（標題）和 count（數目）。sort（排序）的有效值為 asc（遞增）和 desc（遞減）。

per_page（每頁結果）可篩選可限制查詢結果的數目。舉個例說，輸入(per_page: 10)的話，就只會回傳10項紀錄。與查詢物件不同，此數據集不能分頁。

運行playground調試工具 

query {
  areas(lang: "zh-hant", sort_field: "count", sort: "asc") {
    title
    count
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  areas(lang: \\\"zh-hant\\\", sort_field: \\\"count\\\", sort: \\\"asc\\\") { \
    title \
    count \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    areas(lang: "zh-hant", sort_field: "count", sort: "asc") {
      title
      count
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
以範圍篩選物件

若要以範圍篩選物件，請以(area: "XXX") 查詢物件，當中的「XXX」是特定的範圍id。

類別

「類別」指的是物件類型，例如繪畫、家具等。要取得所有類別，你可使用以下方法查詢：

運行playground調試工具 

query {
  categories(lang: "zh-hant", sort_field: "count", sort: "desc") {
    title
    count
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  categories(lang: \\\"zh-hant\\\", sort_field: \\\"count\\\", sort: \\\"desc\\\") { \
    title \
    count \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    categories(lang: "zh-hant", sort_field: "count", sort: "desc") {
      title
      count
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
以類別篩選物件

若要以類別篩選物件，請以(category: "XXX") 查詢物件，當中的「XXX」是特定的類別id。

檔案藏品層次

檔案紀錄與物件的分類有所不同，一組檔案紀錄稱為「全宗」，而每件物件則處於「件」的層面。檔案紀錄的架構為「全宗」、「副全宗」、「系列」、「副系列」、「副副系列」、「案卷」、「件」及「子件」。要取得所有檔案藏品層次，你可使用以下方法查詢：

運行playground調試工具 

query {
  archivalLevels {
    title
    count
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  archivalLevels { \
    title \
    count \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    archivalLevels {
      title
      count
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)

全宗

M+各系列的藏品均編有一個「藏品號碼」。要取得所有藏品號碼，你可使用以下方法查詢：

運行playground調試工具 

query {
  fonds {
    title
    count
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  fonds { \
    title \
    count \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    fonds {
      title
      count
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)

以下例子示範如何調用所有屬於同一藏品號碼的物件。

運行playground調試工具 

query {
  objects(fonds: "CA1") {
    id
    objectNumber
    title
    displayDate
    medium
    classification {
      area
      category
    }
  }
}

媒材

「媒材」指的是創作物件所用的材料。要取得所有媒材，你可使用以下方法查詢：

運行playground調試工具 

query {
  mediums {
    title
    count
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  mediums { \
    title \
    count \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    mediums {
      title
      count
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
以媒材篩選物件

若要以媒材篩選物件，請以(medium: "XXX")查詢物件，當中的「XXX」是特定的媒材id。

相關各方

「相關各方」就是與物件有關的人物和機構，如藝術家、建築師、設計工作室、製造商，或出版社。

這項查詢選擇所有相關各方，並能夠透過以下字段進行篩選。備註：篩選屬累加性質而非任擇其一，篩選兩個字段的話，只會回傳同時吻合兩者的數據。

有效的篩選為：page（頁數）、per_page（每頁結果）、sort_field（字段排序）、sort（排序）、[ids]、gender（性別）、beginDate（開始日期）、endDate（結束日期）、nationality（國籍）和 lang（語言)

sort_field（字段排序）的有效值為 id、name（名字）、sortNumber（排序號碼）、alphaSortName（字母排序名稱）、gender（性別）、beginDate（開始日期）、endDate（結束日期）和 nationality（國籍）。sort（排序）的有效值為 asc（遞增）和 desc（遞減）。

以下是調用所有構成要素ID最簡單的方法

運行playground調試工具 

query {
  constituents {
    id
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  constituents { \
    id \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    constituents {
      id
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
透過id取得

相關各方你亦可以透過輸入一系列 ids，查詢特定的相關各方。

運行playground調試工具 

query {
  constituents(ids:[238, 382, 459, 608], lang: "zh-hant") {
    id
    name
    nameOther
    alphaSortName
    displayBio
    gender
    beginDate
    nationality
    type
    roles
    isMaker
    objectCountPublic
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  constituents(ids:[238, 382, 459, 608], lang: \\\"zh-hant\\\") { \
    id \
    name \
    nameOther \
    alphaSortName \
    displayBio \
    gender \
    beginDate \
    nationality \
    type \
    roles \
    isMaker \
    objectCountPublic \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    constituents(ids:[238, 382, 459, 608], lang: "zh-hant") {
      id
      name
      nameOther
      alphaSortName
      displayBio
      gender
      beginDate
      nationality
      type
      roles
      isMaker
      objectCountPublic
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
相關各方角色

「角色」指的是數據集中相關各方的類型。若你以 makertypes（創作人類型）查詢，你將可得到所有相關各方角色的名單。備註：查詢相關各方時，你只可透過此數據篩選個別的相關各方類型。

運行playground調試工具 

query {
  makertypes {
    title
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  makertypes { \
    title \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    makertypes {
      title
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
透過角色取得相關各方

你可以「角色」取得若所有相關各方。以下例子展示相關各方中所有的「藝術家」，並以物件數量多寡排序。

運行playground調試工具 

query {
  constituents(role:"Artist", isMaker:true, sort_field: "objectCountPublic", sort:"desc") {
    id
    name
    nameOther
    alphaSortName
    displayBio
    gender
    beginDate
    nationality
    type
    roles
    isMaker
    objectCountPublic
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  constituents(role:\\\"Artist\\\", isMaker:true, sort_field: \\\"objectCountPublic\\\", sort:\\\"desc\\\") { \
    id \
    name \
    nameOther \
    alphaSortName \
    displayBio \
    gender \
    beginDate \
    nationality \
    type \
    roles \
    isMaker \
    objectCountPublic \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    constituents(role:"Artist", isMaker:true, sort_field: "objectCountPublic", sort:"desc") {
      id
      name
      nameOther
      alphaSortName
      displayBio
      gender
      beginDate
      nationality
      type
      roles
      isMaker
      objectCountPublic
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
分頁和篩選例子

以下例子示範如何調用更多資料。備註：我們可以用per_page（每頁結果）限制每頁查詢結果的數目。

運行playground調試工具 

query {
  constituents(page:3, per_page: 5, gender: "Female") {
    id
    name
    nameOther
    alphaSortName
    displayBio
    gender
    beginDate
    nationality
    type
    roles
    isMaker
    objectCountPublic
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  constituents(page:3, per_page: 5, gender: \\\"Female\\\") { \
    id \
    name \
    nameOther \
    alphaSortName \
    displayBio \
    gender \
    beginDate \
    nationality \
    type \
    roles \
    isMaker \
    objectCountPublic \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    constituents(page:3, per_page: 5, gender: "Female") {
      id
      name
      nameOther
      alphaSortName
      displayBio
      gender
      beginDate
      nationality
      type
      roles
      isMaker
      objectCountPublic
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
排序

以下是使用alphaSortName（字母排序名稱）進行排序的例子。

運行playground調試工具 

query {
  constituents(sort_field: "alphaSortName", sort: "asc") {
    id
    name
    nameOther
    alphaSortName
    displayBio
    gender
    beginDate
    nationality
    type
    roles
    isMaker
    objectCountPublic
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  constituents(sort_field: \\\"alphaSortName\\\", sort: \\\"asc\\\") { \
    id \
    name \
    nameOther \
    alphaSortName \
    displayBio \
    gender \
    beginDate \
    nationality \
    type \
    roles \
    isMaker \
    objectCountPublic \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    constituents(sort_field: "alphaSortName", sort: "asc") {
      id
      name
      nameOther
      alphaSortName
      displayBio
      gender
      beginDate
      nationality
      type
      roles
      isMaker
      objectCountPublic
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)

相關各方

你可以透過輸入 id 參數，獲得個別相關各方。以下是所有可顯示的字段。

運行playground調試工具 

query {
  constituent(id: 238) {
    id
    name
    nameOther
    alphaSortName
    displayBio
    gender
    beginDate
    nationality
    roles
    type
    objects {
      id
      objectNumber
      title
      displayDate
      medium
      classification {
        area
        category
      }
    }
  }
}

cURL命令 

curl -H "Authorization: bearer null" \
-H "Content-Type: application/json" \
-X POST -d \
"{\"query\": \
\"{ \
  constituent(id: 238) { \
    id \
    name \
    nameOther \
    alphaSortName \
    displayBio \
    gender \
    beginDate \
    nationality \
    roles \
    type \
    objects { \
      id \
      objectNumber \
      title \
      displayDate \
      medium \
      classification { \
        area \
        category \
      } \
    } \
  } \
}\"}" \
https://api.mplus.org.hk/graphql

Node.js 命令 

const request = require('request')

const payload = {
  query: `{
    constituent(id: 238) {
      id
      name
      nameOther
      alphaSortName
      displayBio
      gender
      beginDate
      nationality
      roles
      type
      objects {
        id
        objectNumber
        title
        displayDate
        medium
        classification {
          area
          category
        }
      }
    }
  }`
}

request(
  {
    url: 'https://api.mplus.org.hk/graphql',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      Authorization: 'bearer null'
    },
    json: payload
  },
  (error, resp, body) => {
    if (error) {
      console.log(error)
      // do something
    }
    if ('errors' in body) {
      console.log(body.errors)
      // do something else
    }
    console.log(body.data)
  }
)
把物件嵌套在相關各方內，以及把相關各方嵌套在物件內

當你搜尋物件時，可以從結果中嵌套有限的相關各方。如果你請求物件的話，可以透過以下查詢獲得相關各方。

運行playground調試工具 

query {
  objects {
    id
    objectNumber
    title
    displayDate
    medium
    classification {
      area
      category
    }
    constituents {
      id
      name
      alphaSortName
      displayBio
      gender
      beginDate
      nationality
      role
    }
  }
}

若你請求單一物件，你可獲取稍多有關相關各方的資訊，例子如下：

運行playground調試工具 

query {
  object(id: 119) {
    id
    objectNumber
    title
    displayDate
    medium
    classification {
      area
      category
    }
    constituents {
      id
      name
      alphaSortName
      displayBio
      gender
      beginDate
      nationality
      role
      objects {
        id
        objectNumber
        title
        displayDate
        medium
        classification {
          area
          category
        }
      }
    }
  }
}

超過首兩層後，你不能繼續嵌套物件和相關各方，因為兩者只會不斷互相嵌套。

你亦可在物件內嵌套相關各方，但同樣地，回傳的資訊有限，亦只限於兩層。

尋找與相關各方有關的物件

要尋找與相關各方有關聯的物件，有兩個方法。

1. 如果想尋找所有由某位藝術家創造的物件，可以運行查詢，找出藝術家，亦在該項查詢內請求與該藝術家有關的物件，例子如下：

運行playground調試工具 

query {
  constituent(id: 478) {
    id
    name
    nameOther
    alphaSortName
    displayBio
    gender
    beginDate
    nationality
    roles
    type
    objects {
      id
      objectNumber
      title
      displayDate
      medium
      classification {
        area
        category
      }
    }
  }
}
2. 你亦可以相關各方 id篩選，用以搜尋物件。這個方式的好處是，你可以進一步篩選結果。以下查詢顯示所有與某個相關各方相關，並以個別媒材篩選的物件。

運行playground調試工具 

query {
  objects(constituent: 478) {
    id
    objectNumber
    title
    displayDate
    medium
    classification {
      area
      category
    }
    constituents {
      name
      role
    }
  }
}

展覽

尋找展覽與相關各方的做法完全一樣。以下例子示範如何找到數據集中所有展覽。

運行playground調試工具 

query {
      exhibitions {
        id
        beginDate
        endDate
        venues {
          title
          beginDate
          endDate
        }
      }
}

同樣地，你可透過物件端點找到展覽。以下例子為你示範搜尋個別展覽中所有「繪畫」類的物件，每頁顯示十項結果。

運行playground調試工具 

query {
  objects(exhibition:95, per_page:10, page:0, category:"Painting") {
    id
    title
    classification {
      area
      category
    }
    exhibitions {
      exhibitions {
        id
        beginDate
        endDate
        section
        venues {
          title
          beginDate
          endDate
        }
      }
      labels {
        text
        purpose
      }
    }
    constituents {
      id
      name
      nationality
      gender
      displayBio
      exhibitionBios {
        text
        purpose
      }
    }
  }
}

這樣你就可得知一個展覽中的所有物件。要篩選個別展覽的內客（例如展品說明或藝術家簡介），你須要利用「purpose」字段進行篩選。

個別展覽

若你想取得個別展覽的資料，而又知道展覽的id，即可要求取得個別展覽的資料。以下是中國藝術圖志（1972至2012年）網上展覽的例子，其展覽id是95。

運行playground調試工具 

query {
  exhibition(id:95) {
    id
    beginDate
    endDate
    venues {
      title
      beginDate
      endDate
    }
    objects {
      id
      title
    }
  }
}
文本條目

「文本條目」指的是有關物件及展覽的額外資料，包括功能、物件說明及藝術家簡介。

要取得所有有效的功能條目，你可使用以下方法查詢：

運行playground調試工具 

query {
    exhibition(id: 95) {
      objects {
        id
        title
          exhibitions {
          labels {
            purpose
          }
        }
      }
    }
}

要取得所有有效的物件說明，你可使用以下方法查詢：

運行playground調試工具 

query {
  exhibition(id: 95) {
    objects {
      id
      title
      exhibitions {
        labels {
          purpose
          text
        }
      }
    }
  }
}

要取得所有有效的藝術家簡介，你可使用以下方法查詢：

運行playground調試工具 

query {
  exhibition(id: 95) {
    objects {
      id
      title
      constituents {
        exhibitionBios {
          purpose
          text
        }
      }
    }
  }
}