共用方式為


Operations

取得叢集節點

GET /clusters/{cluster}/nodes

Parameters

類型 Name Description Schema
Path cluster
required
要查詢的叢集 字串
Query operation
optional
如果指定,則只會傳回此作業標識碼的節點,並在本文中包含 operation 屬性 字串
Query request_id
optional
如果指定,則只會傳回此要求標識碼所識別作業的節點,
和包含本文上的作業屬性
字串

Responses

HTTP Code Description Schema
200 OK NodeList
400 Invalid specification No Content
404 Not found No Content

HTTP 要求範例

Request path

/clusters/CLUSTER_NAME/nodes

HTTP 回應範例

Response 200

{
  "nodes" : [ { } ],
  "operation" : {
    "action" : "string",
    "startTime" : "2020-01-01T12:34:56Z"
  }
}

建立叢集節點

POST /clusters/{cluster}/nodes/create

Description

這項作業會將節點陣列中的新節點新增至叢集。 它會在單一呼叫中接受多個節點定義。 它會傳回可用來追蹤作業狀態的作業 URL。

Parameters

類型 Name Description Schema
Path cluster
required
要新增節點的叢集 字串
Body nodes
required
要建立的節點集 NodeCreationRequest

Responses

HTTP Code Description Schema
202 Accepted
Headers :
Location (string) :作業的 URL。
NodeCreationResult
409 Invalid input No Content

HTTP 要求範例

Request path

/clusters/CLUSTER_NAME/nodes/create

Request body

{
  "requestId" : "00000000-0000-0000-0000-000000000000",
  "sets" : [ "object" ]
}

HTTP 回應範例

Response 202

{
  "operationId" : "00000000-0000-0000-0000-000000000000",
  "sets" : [ "object" ]
}

解除分配叢集節點

POST /clusters/{cluster}/nodes/deallocate

Description

這項作業會解除分配叢集中的節點。 您可以使用數種方法來識別節點,包括節點名稱、節點標識碼或篩選。

Parameters

類型 Name Description Schema
Path cluster
required
您要解除分配節點的叢集 字串
Body action
required
要解除分配的節點描述 NodeManagementRequest

Responses

HTTP Code Description Schema
202 Accepted
Headers :
Location (string) :作業的 URL。
NodeManagementResult
409 Invalid input No Content

HTTP 要求範例

Request path

/clusters/CLUSTER_NAME/nodes/deallocate

Request body

{
  "filter" : "State === \"Started\"",
  "hostnames" : [ "hostname1", "hostname2" ],
  "ids" : [ "id1", "id2" ],
  "ip_addresses" : [ "10.0.1.1", "10.1.1.2" ],
  "names" : [ "name1", "name2" ],
  "requestId" : "00000000-0000-0000-0000-000000000000"
}

HTTP 回應範例

Response 202

{
  "nodes" : [ "object" ],
  "operationId" : "00000000-0000-0000-0000-000000000000"
}

終止和移除叢集節點

POST /clusters/{cluster}/nodes/remove

Description

此作業會移除叢集中的節點。 您可以使用數種方式來識別節點,包括節點名稱、節點標識符,或使用篩選。 根據預設,除非節點將 Fixed 屬性設定為 true,否則終止時會移除節點。 在此情況下,此呼叫的作用與終止相同。

Parameters

類型 Name Description Schema
Path cluster
required
您要移除節點的叢集 字串
Body action
required
要移除哪些節點的描述 NodeManagementRequest

Responses

HTTP Code Description Schema
202 Accepted
Headers :
Location (string) :作業的 URL。
NodeManagementResult
409 Invalid input No Content

HTTP 要求範例

Request path

/clusters/CLUSTER_NAME/nodes/remove

Request body

{
  "filter" : "State === \"Started\"",
  "hostnames" : [ "hostname1", "hostname2" ],
  "ids" : [ "id1", "id2" ],
  "ip_addresses" : [ "10.0.1.1", "10.1.1.2" ],
  "names" : [ "name1", "name2" ],
  "requestId" : "00000000-0000-0000-0000-000000000000"
}

HTTP 回應範例

Response 202

{
  "nodes" : [ "object" ],
  "operationId" : "00000000-0000-0000-0000-000000000000"
}

終止或解除分配叢集節點

POST /clusters/{cluster}/nodes/shutdown

Description

此作業會終止或解除分配叢集中的節點。 作業會在每個節點上使用 ShutdownPolicy 屬性來判斷動作。 如果 屬性設定為 Terminate (預設值),作業就會終止節點。 如果屬性設定為 Deallocate,則作業會解除分配節點。

Parameters

類型 Name Description Schema
Path cluster
required
您要關閉節點的叢集 字串
Body action
required
要關閉之節點的描述 NodeManagementRequest

Responses

HTTP Code Description Schema
202 Accepted
Headers :
Location (string) :作業的 URL。
NodeManagementResult
409 Invalid input No Content

HTTP 要求範例

Request path

/clusters/CLUSTER_NAME/nodes/shutdown

Request body

{
  "filter" : "State === \"Started\"",
  "hostnames" : [ "hostname1", "hostname2" ],
  "ids" : [ "id1", "id2" ],
  "ip_addresses" : [ "10.0.1.1", "10.1.1.2" ],
  "names" : [ "name1", "name2" ],
  "requestId" : "00000000-0000-0000-0000-000000000000"
}

HTTP 回應範例

Response 202

{
  "nodes" : [ "object" ],
  "operationId" : "00000000-0000-0000-0000-000000000000"
}

啟動已解除分配或終止的叢集節點

POST /clusters/{cluster}/nodes/start

Description

此作業會啟動叢集中的節點。 您可以透過節點名稱、節點識別碼或使用篩選來識別節點。

Parameters

類型 Name Description Schema
Path cluster
required
要啟動節點的叢集 字串
Body action
required
要啟動哪些節點的描述 NodeManagementRequest

Responses

HTTP Code Description Schema
202 Accepted
Headers :
Location (string) :作業的 URL。
NodeManagementResult
409 Invalid input No Content

HTTP 要求範例

Request path

/clusters/CLUSTER_NAME/nodes/start

Request body

{
  "filter" : "State === \"Started\"",
  "hostnames" : [ "hostname1", "hostname2" ],
  "ids" : [ "id1", "id2" ],
  "ip_addresses" : [ "10.0.1.1", "10.1.1.2" ],
  "names" : [ "name1", "name2" ],
  "requestId" : "00000000-0000-0000-0000-000000000000"
}

HTTP 回應範例

Response 202

{
  "nodes" : [ "object" ],
  "operationId" : "00000000-0000-0000-0000-000000000000"
}

終止叢集節點

POST /clusters/{cluster}/nodes/terminate

Description

這項作業會終止叢集中的節點。 您可以使用數種方式來識別節點,包括節點名稱、節點標識符,或使用篩選。

Parameters

類型 Name Description Schema
Path cluster
required
您要終止節點的叢集 字串
Body action
required
要終止之節點的描述 NodeManagementRequest

Responses

HTTP Code Description Schema
202 Accepted
Headers :
Location (string) :作業的 URL。
NodeManagementResult
409 Invalid input No Content

HTTP 要求範例

Request path

/clusters/CLUSTER_NAME/nodes/terminate

Request body

{
  "filter" : "State === \"Started\"",
  "hostnames" : [ "hostname1", "hostname2" ],
  "ids" : [ "id1", "id2" ],
  "ip_addresses" : [ "10.0.1.1", "10.1.1.2" ],
  "names" : [ "name1", "name2" ],
  "requestId" : "00000000-0000-0000-0000-000000000000"
}

HTTP 回應範例

Response 202

{
  "nodes" : [ "object" ],
  "operationId" : "00000000-0000-0000-0000-000000000000"
}

將叢集調整為大小

POST /clusters/{cluster}/scale/{nodearray}

Description

此作業會視需要將節點新增至節點數位,以達到總計數。 叢集會處理要求一次。 稍後不會重新新增節點來維護數位。 您可以依核心總數或節點總數進行調整,但不能同時調整兩者。 作業會傳回用來追蹤作業狀態的URL。

Parameters

類型 Name Description Schema
Path cluster
required
要新增節點的叢集 字串
Path nodearray
required
要加入節點的節點陣列 字串
Query totalCoreCount
optional
此節點陣列中的核心總數,包括您已建立的節點 整數
Query totalNodeCount
optional
此節點陣列中的機器總數,包括您已建立的節點 整數

Responses

HTTP Code Description Schema
202 Accepted
Headers :
Location (string) :作業的 URL。
NodeCreationResult
409 Invalid input No Content

HTTP 要求範例

Request path

/clusters/CLUSTER_NAME/scale/NODEARRAY_NAME

HTTP 回應範例

Response 202

{
  "operationId" : "00000000-0000-0000-0000-000000000000",
  "sets" : [ "object" ]
}

取得叢集狀態

GET /clusters/{cluster}/status

Description

此作業會傳回叢集中節點和節點數位的資訊。 針對每個節點陣列,它會傳回您可以使用之配置的每個「貯體」狀態。 狀態會顯示貯體中的節點數目,以及您可以新增的節點數目。 每個貯體都是一組具有特定硬體配置檔的可能 VM。 您可以在客戶帳戶下的特定位置建立這些 VM。 使用者的叢集定義會決定節點陣列的有效貯體。 雲端提供者會決定限制。

Parameters

類型 Name Description Schema
Path cluster
required
要查詢的叢集 字串
Query nodes
optional
如果為 true,回應會包含節點和節點參考 boolean

Responses

HTTP Code Description Schema
200 OK ClusterStatus

HTTP 要求範例

Request path

/clusters/CLUSTER_NAME/status

HTTP 回應範例

Response 200

{
  "maxCoreCount" : 16,
  "maxCount" : 4,
  "nodearrays" : [ "object" ],
  "nodes" : [ { } ],
  "state" : "Starting",
  "targetState" : "Started"
}

取得叢集的使用方式和選擇性成本資訊

GET /clusters/{cluster}/usage

Description

此作業會傳回叢集的整體使用量數據(核心時數)和成本數據,以及每個節點數位明細。 根據預設,它會傳回當月使用量的值。

Parameters

類型 Name Description Schema
Path cluster
required
要傳回使用量數據的叢集 字串
Query timeframe
optional
查詢的時間範圍。 monthToDate 會傳回目前月份的使用量,而 lastMonth 會傳回上個月的使用量。 weekToDate 會傳回目前一周的使用量(從星期日開始)。 自定義需要 『from』 和 『to』 查詢參數。 預設值為 MonthToDate。 所有時間都是採用 UTC 格式。 enum (monthToDate, lastMonth, weekToDate, custom)
Query from
optional
針對自定義時間範圍,以 ISO-8601 格式的時間範圍開頭。 值會四捨五入為最接近的小時或一天。 字串
Query to
optional
針對自訂時間範圍,請使用 ISO-8601 格式的時間範圍結尾。 值會四捨五入到最接近的小時或一天。 字串
Query granularity
optional
指定如何匯總數據:依小時、每日或單一數位。 預設值為每日。 列舉 (總計、每日、每小時)

Responses

HTTP Code Description Schema
200 OK ClusterUsage

HTTP 要求範例

Request path

/clusters/CLUSTER_NAME/usage

HTTP 回應範例

Response 200

{
  "usage" : [ "object" ]
}

列出作業的狀態

GET /operations/

Parameters

類型 Name Description Schema
Query request_id
optional
作業的要求標識碼。 如果您提供此標識碼,清單會包含零或一個專案。 字串

Responses

HTTP Code Description Schema
200 OK < OperationStatus> array
400 Invalid request No Content
404 Not found No Content

HTTP 要求範例

Request path

/operations/

HTTP 回應範例

Response 200

[ {
  "action" : "string",
  "startTime" : "2020-01-01T12:34:56Z"
} ]

依標識碼取得作業狀態

GET /operations/{id}

Parameters

類型 Name Description Schema
Path id
required
作業標識碼 字串

Responses

HTTP Code Description Schema
200 OK OperationStatus
404 Not found No Content

HTTP 要求範例

Request path

/operations/00000000-0000-0000-0000-000000000000

HTTP 回應範例

Response 200

{
  "action" : "string",
  "startTime" : "2020-01-01T12:34:56Z"
}

Resources

ClusterStatus

叢集的狀態。

Name Description Schema
maxCoreCount
required
您可以新增至此叢集的核心數目上限。
Example : 16
整數
maxCount
required
您可以新增至此叢集的節點數目上限。
Example : 4
整數
nodearrays
required
Example : [ "object" ] < nodearrays> array
nodes
optional
此叢集中的節點選擇性清單。 只有在您在查詢中設定 nodes=true 時,回應才會包含此清單。
Example : [ "[node](#node)" ]
< Node> array
state
optional
如果叢集至少啟動一次,則為叢集的目前狀態
Example : "Starting"
字串
targetState
optional
叢集所需的狀態(例如,已啟動或終止)
Example : "Started"
字串

nodearrays

Name Description Schema
buckets
required
此節點陣列的每個配置區。 「核心計數」設定一律是這個貯體的核心計數的倍數。
Example : [ "object" ]
< buckets> array
maxCoreCount
required
此節點陣列中的核心數目上限
Example : 16
整數
maxCount
required
此節點陣列中的節點數目上限
Example : 4
整數
name
required
節點陣列名稱
Example : "execute"
字串
nodearray
required
這個節點陣列的屬性
Example : "[node](#node)"
Node

buckets

Name Description Schema
activeCoreCount
required
此節點陣列中用於此貯體的核心數目
Example : 40
整數
activeCount
required
在此節點陣列中,用於此貯體中的節點數目。 此計數包含仍在取得 VM 的節點。
Example : 10
整數
activeNodes
optional
用於此貯體之節點名稱,在此節點陣列中。 此清單包含仍在取得 VM 的節點。 只有在查詢包含 nodes=true時,回應才會包含這個屬性。
Example : [ "string" ]
< 字串 > 陣列
availableCoreCount
required
您可以在此貯體和節點陣列中建立多少個額外的核心。 這個值一律為的倍數 availableCount
Example : 8
整數
availableCount
required
您可以在此貯體和節點陣列中建立多少個額外的節點。 此值可能小於您在從 maxCount減去 usedCount 時得到的數字,因為maxCount可能會有全域限制。
Example : 2
整數
bucketId
required
這個貯體的標識碼。 只要您不刪除叢集,此值就會在節點陣列中保留相同的值區。
Example : "00000000-0000-0000-0000-000000000000"
字串
consumedCoreCount
required
此系列的核心數目已在整個區域使用中。
Example : 2
整數
definition
optional
這個貯體的屬性,用來從這個貯體建立節點。 create-nodes API 會在其 bucket 屬性中採用此定義。
Example : "object"
definition
familyConsumedCoreCount
optional
此系列的核心數目已在整個區域使用中。
Example : 2
整數
familyQuotaCoreCount
optional
您可以在此區域中開始此系列的核心總數。 這個數位可能不是 quotaCount 的整數倍數。
Example : 16
整數
familyQuotaCount
optional
設定 familyQuotaCoreCount 時可以啟動的總實例數目。
Example : 4
整數
invalidReason
required
如果 valid 為 false,字段會包含貯體無效的原因。 目前 NotActivated 和 DisabledMachineType 是唯一的原因。
Example : "DisabledMachineType"
字串
lastCapacityFailure
required
自從上次此貯體發生容量失敗以來,以秒為單位的時間長度。 任何負值都會被視為永不。
Example : 180.0
number
maxCoreCount
required
此貯體中可包含的核心數目上限,包括全域和 nodearray 限制。 一律是 MaxCount的倍數。
Example : 16
整數
maxCount
required
可在此貯體中的節點數目上限,包括全域和 nodearray 限制
Example : 4
整數
maxPlacementGroupCoreSize
required
此貯體放置群組中的核心總數上限。 一律為的倍數 maxPlacementGroupSize
Example : 64
整數
maxPlacementGroupSize
required
此貯體放置群組中的實例總數上限。
Example : 16
整數
placementGroups
required
用於此節點陣列的放置群組,如果有的話。
Example : [ "object" ]
< placementGroups> array
quotaCoreCount
required
您可以在此區域中開始此系列的核心總數。 此數位也會考慮區域配額核心計數。 此值可能不是 quotaCount 的整數倍數。
Example : 16
整數
quotaCount
required
指定 quotaCoreCount,您可以啟動的總實例數目。
Example : 4
整數
regionalConsumedCoreCount
optional
已在整個區域中使用的核心數目。
Example : 2
整數
regionalQuotaCoreCount
optional
您可以在此區域中啟動的核心總數。 這個數位可能不是地區QuotaCount的整數倍數。
Example : 16
整數
regionalQuotaCount
optional
您可以啟動的實體總數(指定地區QuotaCoreCount)
Example : 4
整數
valid
required
如果為 true,則此貯體代表目前用於新節點的有效貯體。 如果為 false,則此貯體僅代表現有的節點。
Example : true
boolean
virtualMachine
required
您從這個貯體啟動之虛擬機的屬性
Example : "object"
virtualMachine

definition

Name Description Schema
machineType
required
虛擬機的 VM 大小
Example : "A2"
字串

placementGroups

Name Description Schema
activeCoreCount
required
此擴展集中的核心數目
Example : 16
整數
activeCount
required
此擴展集中的節點數目
Example : 4
整數
name
required
這個放置群組的唯一標識碼
Example : "my-placement-group"
字串

virtualMachine

Name Description Schema
gpuCount
required
此電腦類型具有的 GPU 數目
Example : 2
整數
infiniband
required
如果此虛擬機支援 InfiniBand 連線能力
Example : true
boolean
memory
required
此虛擬機中的 RAM,以 GB 為單位
Example : 7.5
number
pcpuCount
required
此電腦類型具有的實體CPU數目
Example : 16
整數
vcpuCount
required
此機器類型的虛擬 CPU 數目
Example : 32
整數
vcpuQuotaCount
optional
此電腦從配額使用的 vCPU 數目
Example : 2
整數

ClusterUsage

叢集的使用方式和選擇性成本資訊

Name Description Schema
usage
required
依時間間隔的使用量清單
Example : [ "object" ]
< usage> array

usage

Name Description Schema
breakdown
required
此間隔中的使用量明細,依 “node” 和 “nodearray” 類別
Example : [ "[clusterusageitem](#clusterusageitem)" ]
< ClusterUsageItem> array
end
required
間隔結尾 (獨佔)
Example : "string"
字串
start
required
間隔的開頭(含)
Example : "string"
字串
total
required
此叢集在此間隔內的整體使用量,其類別為「叢集」
Example : "[clusterusageitem](#clusterusageitem)"
ClusterUsageItem

ClusterUsageItem

Name Description Schema
category
required
整體使用量的「叢集」;單一非陣列前端節點的 「node」 ;整個 nodearray 的 “nodearray”
Example : "string"
enum (cluster, node, nodearray)
cost
optional
此使用量的費用,以美元和零售費率計算。 注意:所有成本金額都是估計值,且不會反映實際帳單!
Example : 0.0
number
details
optional
nodearray 所使用的 VM 大小詳細數據,包括小時、核心計數、區域優先順序和作系統。
Example : [ "object" ]
< details> array
hours
required
此類別的核心使用時數
Example : 0.0
number
node
optional
使用方式為節點或節點陣列名稱(叢集層級資料不存在)
Example : "string"
字串

details

Name Description Schema
core_count
optional
此 VM 大小的核心數目
Example : 0.0
number
cost
optional
此 VM 大小的成本
Example : 0.0
number
hours
optional
此 VM 大小的核心時數
Example : 0.0
number
os
optional
作系統類型
Example : "string"
列舉 (Windows, Linux)
priority
optional
VM Sku 的優先順序
Example : "string"
列舉(一般,現成)
region
optional
具現化 VM 大小的區域
Example : "string"
字串
vm_size
optional
VM Sku 大小
Example : "string"
字串

Node

節點記錄。

Type : object

NodeCreationRequest

指定如何將節點新增至叢集。

Name Description Schema
requestId
optional
選擇性使用者提供的唯一令牌,以防止發生網路通訊錯誤時重複的作業。 如果伺服器收到與 requestId 先前要求相符的要求,則會忽略要求並傳回 409 錯誤。
Example : "00000000-0000-0000-0000-000000000000"
字串
sets
required
要建立的節點定義清單。 要求必須至少包含一組。 每個集合都可以指定一組不同的屬性。
Example : [ "object" ]
< sets> array

sets

Name Description Schema
count
required
要建立的節點數目
Example : 1
整數
definition
optional
要使用的貯體定義。 叢集狀態 API 呼叫會提供此定義。 如果定義遺漏狀態呼叫或整個bucket屬性中指定的某些專案,則會使用符合指定專案的第一個貯體。
Example : "object"
definition
nameFormat
optional
如果您提供此值,節點會使用此命名慣例,而不是標準 nodearray-%d 格式
Example : "custom-name-%d"
字串
nameOffset
optional
如果您提供這個屬性, nameFormat則新節點的屬性位移 nodeindex
Example : 1
整數
nodeAttributes
optional
要在此集合中每個節點上設定的額外屬性
Example : "[node](#node)"
Node
nodearray
required
要從中啟動節點的 nodearray 名稱
Example : "execute"
字串
placementGroupId
optional
如果您提供這個屬性,則節點在相同的放置群組中,具有相同值 groupId 的所有開始。
Example : "string"
字串

definition

Name Description Schema
machineType
optional
Example : "A2" 字串

NodeCreationResult

Name Description Schema
operationId
required
作業的標識碼
Example : "00000000-0000-0000-0000-000000000000"
字串
sets
required
集合陣列,順序與要求中的順序相同
Example : [ "object" ]
< sets> array

sets

Name Description Schema
added
required
要加入集合中的節點數目
Example : 1
整數
message
optional
說明系統為何若存在,則無法新增所有要求的節點
Example : "string"
字串

NodeList

節點搜尋的結果

Name Description Schema
nodes
required
系統傳回的節點
Example : [ "[node](#node)" ]
< Node> array
operation
optional
如果查詢包含作業標識碼,此欄位會顯示該作業的狀態
Example : "[operationstatus](#operationstatus)"
OperationStatus

NodeManagementRequest

指定如何在叢集中的節點上執行動作。 您可以透過多種方式指定節點。 如果您包含多個方式,要求會將規格視為等位。

Name Description Schema
filter
optional
符合節點的篩選條件表達式。 請注意,表達式中的字串必須正確加上引號。
Example : "State === \"Started\""
字串
hostnames
optional
要管理的簡短主機名清單(沒有網域)
Example : [ "hostname1", "hostname2" ]
< 字串 > 陣列
ids
optional
要管理的節點識別碼清單
Example : [ "id1", "id2" ]
< 字串 > 陣列
ip_addresses
optional
要管理的IP位址清單
Example : [ "10.0.1.1", "10.1.1.2" ]
< 字串 > 陣列
names
optional
要管理的節點名稱清單
Example : [ "name1", "name2" ]
< 字串 > 陣列
requestId
optional
選擇性使用者提供的唯一令牌,以防止發生網路通訊錯誤時重複的作業。 如果伺服器收到與 requestId 先前要求標識符相符的要求,則會忽略要求並傳回 409 錯誤。
Example : "00000000-0000-0000-0000-000000000000"
字串

NodeManagementResult

Name Description Schema
nodes
required
與管理要求中篩選條件相符之每個節點的相關信息陣列。 每個節點的狀態都會指出要求是否會影響它。
Example : [ "object" ]
< nodes> array
operationId
required
此作業的識別碼
Example : "00000000-0000-0000-0000-000000000000"
字串

nodes

Name Description Schema
error
optional
如果狀態為 Error,則錯誤訊息
Example : "This node must be terminated before it can be removed"
字串
id
required
節點的標識碼
Example : "id1"
字串
name
required
節點的名稱
Example : "name1"
字串
status
optional
其中一個 [確定] 或 [錯誤]
Example : "Error"
列舉 (確定錯誤)

OperationStatus

節點作業的狀態。

Name Description Schema
action
required
Example : "string" enum (create)
startTime
required
提交作業時
Example : "2020-01-01T12:34:56Z"
string (date-time)