Consul官方文档【译文】5、目录

Catalog HTTP API

/catalog

»注册实体

PUT

/catalog/register

application/json

NO

none

node:write,service:write

参数

ID

(string: "")

Node

(string: <required>)

Address

(string: <required>)

Datacenter

(string: "")

TaggedAddresses

(map<string|string>: nil)

NodeMeta

(map<string|string>: nil)

Service

(Service: nil)

ID

Service.Service

ID

Tags

Address

Port

Check

(Check: nil)

CheckID

Name

Service.ID

CheckID

Notes

ID

ServiceID

Status

passing

warning

critical

Checks

Check

Check

Service

»样本有效载荷

{
"Datacenter" :   "dc1" ,
"ID" :   "40e4a748-2192-161a-0510-9bf59fe950b5" ,
"Node" :   "foobar" ,
"Address" :   "192.168.10.10" ,
"TaggedAddresses" :   {
"lan" :   "192.168.10.10" ,
"wan" :   "10.0.10.10"
},
"NodeMeta" :   {
"somekey" :   "somevalue"
},
"Service" :   {
"ID" :   "redis1" ,
"Service" :   "redis" ,
"Tags" :   [
"primary" ,
"v1"
],
"Address" :   "127.0.0.1" ,
"Port" :   8000
},
"Check" :   {
"Node" :   "foobar" ,
"CheckID" :   "service:redis1" ,
"Name" :   "Redis health check" ,
"Notes" :   "Script based health check" ,
"Status" :   "passing" ,
"ServiceID" :   "redis1"
}
}

»Request Sample

$ curl \ --request PUT \ --data @payload.json \ https://consul.rocks/v1/catalog/register[/code] 
拒绝实体
此端点是用于直接从目录中删除条目的低级机制。 通常优选使用代理端点进行注销，因为它们更简单并且执行反熵 。

方法
路径
产生
PUT
/catalog/deregister
application/json
下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询
一致性模式
ACL必需
NO
none
node:write,service:write
参数
端点的行为取决于提供的密钥。

Node 
(string: <required>)
 - 指定节点的ID。 如果没有提供其他值，则会删除此节点，其所有服务及其所有检查。

Datacenter 
(string: "")
 - 指定数据中心，如果未提供，则默认为代理的数据中心。

CheckID 
(string: "")
 - 指定要删除的检查的ID。

ServiceID 
(string: "")
 - 指定要删除的服务的ID。 服务和所有关联的检查将被删除。

»样本有效载荷
{
"Datacenter" :   "dc1" ,
"Node" :   "foobar"
}

{
"Datacenter" :   "dc1" ,
"Node" :   "foobar" ,
"CheckID" :   "service:redis1"
}

{
"Datacenter" :   "dc1" ,
"Node" :   "foobar" ,
"ServiceID" :   "redis1"
}


Request Sample
$ curl \ --request PUT \ --data @payload.json \ https://consul.rocks/v1/catalog/deregister[/code] 
»列出数据中心
此端点返回所有已知数据中心的列表。 基于从服务器到该数据中心的服务器的估计中值往返时间，数据中心将按升序排序。

此端点不需要集群管理员，即使在可用性中断期间也将成功。 因此，它可以作为一个简单的检查来查看是否有任何领事服务器可路由。

方法
路径
产生
GET
/catalog/datacenters
application/json
下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询
一致性模式
ACL必需
NO
none
none
»Request Sample
$ curl \ https://consul.rocks/v1/catalog/datacenters[/code] 
»Response Sample
[ "dc1" ,   "dc2" ]


»列出节点
此端点并返回在给定数据中心中注册的节点。

方法
路径
产生
GET
/catalog/nodes
application/json
下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询
一致性模式
ACL必需
YES
all
node:read
参数
dc 
(string: "")
 - 指定要查询的数据中心。 这将默认为要查询的代理的数据中心。 这是作为查询参数的URL的一部分指定的。

near 
(string: "")
 - 指定一个节点名称，以根据从该节点估计的往返时间按升序对节点列表进行排序。 传递
?near=_agent
将使用代理的节点进行排序。 这是作为查询参数的URL的一部分指定的。

node-meta 
(string: "")
 - 指定表单
key:value
的所需节点元数据键/值对。 可以多次指定此参数，并将结果过滤到具有指定键/值对的节点。 这是作为查询参数的URL的一部分指定的。

»Request Sample
$ curl \ https://consul.rocks/v1/catalog/nodes[/code] 
»Response Sample
[
{
"ID" :   "40e4a748-2192-161a-0510-9bf59fe950b5" ,
"Node" :   "baz" ,
"Address" :   "10.1.10.11" ,
"Datacenter" :   "dc1" ,
"TaggedAddresses" :   {
"lan" :   "10.1.10.11" ,
"wan" :   "10.1.10.11"
},
"Meta" :   {
"instance_type" :   "t2.medium"
}
},
{
"ID" :   "8f246b77-f3e1-ff88-5b48-8ec93abf3e05" ,
"Node" :   "foobar" ,
"Address" :   "10.1.10.12" ,
"Datacenter" :   "dc2" ,
"TaggedAddresses" :   {
"lan" :   "10.1.10.11" ,
"wan" :   "10.1.10.12"
},
"Meta" :   {
"instance_type" :   "t2.large"
}
}
]


»列表服务
此端点返回在给定数据中心中注册的服务。

方法
路径
产生
GET
/catalog/services
application/json
下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询
一致性模式
ACL必需
YES
all
service:read
参数
dc 
(string: "")
 - 指定要查询的数据中心。 这将默认为要查询的代理的数据中心。 这是作为查询参数的URL的一部分指定的。

node-meta 
(string: "")
 - 指定表单
key:value
的所需节点元数据键/值对。 可以多次指定此参数，并将结果过滤到具有指定键/值对的节点。 这是作为查询参数的URL的一部分指定的。

»Request Sample
$ curl \ https://consul.rocks/v1/catalog/services[/code] 
»Response Sample
{
"consul" :   [],
"redis" :   [],
"postgresql" :   [
"primary" ,
"secondary"
]
}

键是服务名称，数组值为给定服务提供所有已知的标签。

»列出服务节点
此端点返回在给定数据中心中提供服务的节点。

方法
路径
产生
GET
/catalog/service/:service
application/json
下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询
一致性模式
ACL必需
YES
all
node:read,service:read
参数
service 
(string: <required>)
 - 指定要为其列出节点的服务的名称。 这是URL的一部分。

dc 
(string: "")
 - 指定要查询的数据中心。 这将默认为要查询的代理的数据中心。 这是作为查询参数的URL的一部分指定的。

tag 
(string: "")
 - 指定要过滤的标签。

near 
(string: "")
 - 指定一个节点名称，以根据从该节点估计的往返时间按升序对节点列表进行排序。 传递
?near=_agent
将使用代理的节点进行排序。 这是作为查询参数的URL的一部分指定的。

node-meta 
(string: "")
 - 指定表单
key:value
的所需节点元数据键/值对。 可以多次指定此参数，并将结果过滤到具有指定键/值对的节点。 这是作为查询参数的URL的一部分指定的。

Request Sample
$ curl \ https://consul.rocks/v1/catalog/service/my-service[/code] 
»Response Sample
[
{
"ID" :   "40e4a748-2192-161a-0510-9bf59fe950b5" ,
"Node" :   "foobar" ,
"Address" :   "192.168.10.10" ,
"Datacenter" :   "dc1" ,
"TaggedAddresses" :   {
"lan" :   "192.168.10.10" ,
"wan" :   "10.0.10.10"
},
"Meta" :   {
"instance_type" :   "t2.medium"
},
"CreateIndex" :   51 ,
"ModifyIndex" :   51 ,
"ServiceAddress" :   "172.17.0.3" ,
"ServiceEnableTagOverride" :   false ,
"ServiceID" :   "32a2a47f7992:nodea:5000" ,
"ServiceName" :   "foobar" ,
"ServicePort" :   5000 ,
"ServiceTags" :   [
"tacos"
]
}
]


Address是服务注册的领事节点的IP地址。

Datacenter是服务注册的领事馆节点的数据中心。

TaggedAddresses是代理的显式LAN和WAN IP地址列表

Meta是节点的用户定义的元数据键/值对列表

CreateIndex是表示服务创建时的内部索引值

ModifyIndex是修改服务的最后一个索引

Node是服务注册的领事节点的名称

ServiceAddress是服务主机的IP地址 - 如果为空，则应使用节点地址

ServiceEnableTagOverride指示服务标签是否可以覆盖此服务

ServiceID是唯一的服务实例标识符

ServiceName是服务的名称

ServicePort是服务的端口号

ServiceTags是服务的标签列表

»节点列表服务
此端点返回节点的注册服务。

方法
路径
产生
GET
/catalog/node/:node
application/json
下表显示了此端点对阻止查询和一致性模式的支持。

下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询
一致性模式
ACL必需
YES
all
node:read,service:read
参数
node 
(string: <required>)
 - 指定要为其列出服务的节点的名称。 这是URL的一部分。

dc 
(string: "")
 - 指定要查询的数据中心。 这将默认为要查询的代理的数据中心。 这是作为查询参数的URL的一部分指定的。

»Request Sample
$ curl \ https://consul.rocks/v1/catalog/node/my-node[/code] 
»Response Sample
{
"Node" :   {
"ID" :   "40e4a748-2192-161a-0510-9bf59fe950b5" ,
"Node" :   "foobar" ,
"Address" :   "10.1.10.12" ,
"Datacenter" :   "dc1" ,
"TaggedAddresses" :   {
"lan" :   "10.1.10.12" ,
"wan" :   "10.1.10.12"
},
"Meta" :   {
"instance_type" :   "t2.medium"
}
},
"Services" :   {
"consul" :   {
"ID" :   "consul" ,
"Service" :   "consul" ,
"Tags" :   null ,
"Port" :   8300
},
"redis" :   {
"ID" :   "redis" ,
"Service" :   "redis" ,
"Tags" :   [
"v1"
],
"Port" :   8000
}
}
}