Consul官方文档【译文】4-2、Service - Agent HTTP API

• Service - Agent HTTP API

/agent/service端点与Consul中本地代理的检查进行交互。 这些不应该与目录中的服务混淆。

»列表服务

此端点返回在本地代理程序中注册的所有服务。 这些服务是通过配置文件提供的，也可以使用HTTP API动态添加。

重要的是要注意，代理人知道的服务可能与目录中报告的服务不同。 这通常是由于在没有领导人当选的情况下进行的改变。 代理执行有效的反熵 ，所以在大多数情况下，所有内容都会在几秒钟内同步。

方法	路径	产生
GET	/agent/services	application/json

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

阻止查询	一致性模式	ACL必需
NO	none	service:read

Request Sample

$ curl \ https://consul.rocks/v1/agent/services

Response Sample 

{ 
   "redis" :   { 
     "ID" :   "redis" , 
     "Service" :   "redis" , 
     "Tags" :   null , 
     "Address" :   "" , 
     "Port" :   8000 
   } 
 } 

»注册服务

此端点向本地代理添加了一项新的可用的运行状况检查服务。

代理负责管理其本地服务的状态，并将其本地服务的更新发送到服务器，以使全局目录保持同步。

方法	路径	产生
PUT	/agent/service/register	application/json

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

阻止查询	一致性模式	ACL必需
NO	none	service:write

参数

• Name (string: <required>) - 指定服务的逻辑名称。 许多服务实例可以共享相同的逻辑服务名称。

• ID (string: "") - 指定此服务的唯一ID。 每个代理人必须是唯一的。 如果没有提供，则默认为Name参数。

• Tags (array<string>: nil) - 指定要分配给服务的标签列表。 这些标签可以用于后续过滤，并通过API公开。

• Address (string: "") - 指定服务的地址。 如果没有提供，则在DNS查询期间，代理的地址将用作服务的地址。

• Check (Check: nil) - 指定检查。 有关接受字段的更多信息，请参阅检查文档 。 如果您不提供用于支票的名称或身份证件，则会生成这些名称或身份证件。 要提供自定义ID和/或名称设置CheckID和/或Name字段。

• Checks (array<Check>: nil ） - 指定检查列表。 有关接受字段的更多信息，请参阅检查文档 。 如果您不提供用于支票的名称或身份证件，则会生成这些名称或身份证件。 要提供自定义ID和/或名称设置CheckID和/或Name字段。 自动生成的Name和CheckID取决于数组中支票的位置，因此即使行为是确定性的，建议所有支票通过将该字段留空或省略或提供一个独特的价值。

• EnableTagOverride (bool: false) - 指定禁用此服务标签的反熵特征。 如果EnableTagOverride设置为true则外部代理可以更新目录中的此服务并修改标记。 此代理的后续本地同步操作将忽略更新的标签。 例如，如果外部代理修改了此服务的标签和端口，并将EnableTagOverride设置为true则在下一个同步周期后，服务的端口将恢复为原始值，但标记将维护更新的值。 作为一个例子，如果外部代理修改了此服务的标签和端口，并且EnableTagOverride设置为false则在下一个同步周期之后，服务的端口和标签将恢复为原始值，并且所有修改都将丢失。

  请注意，这仅适用于本地注册的服务。 如果您有多个节点都注册相同的服务，那么它们的EnableTagOverride配置和所有其他服务配置项彼此独立。 更新在一个节点上注册的服务的标签与在另一个节点上注册的相同服务（按名称）无关。 如果未指定EnableTagOverride则默认值为false 。 有关更多信息，请参阅反熵同步 。

»样本有效载荷

{ 
   "ID" :   "redis1" , 
   "Name" :   "redis" , 
   "Tags" :   [ 
     "primary" , 
     "v1" 
   ], 
   "Address" :   "127.0.0.1" , 
   "Port" :   8000 , 
   "EnableTagOverride" :   false , 
   "Check" :   { 
     "DeregisterCriticalServiceAfter" :   "90m" , 
     "Script" :   "/usr/local/bin/check_redis.py" , 
     "HTTP" :   "http://localhost:5000/health" , 
     "Interval" :   "10s" , 
     "TTL" :   "15s" 
   } 
 } 

Request Sample

$ curl \ --request PUT \ --data @payload.json \ https://consul.rocks/v1/agent/service/register

拒绝服务

此端点从本地代理中删除服务。 如果服务不存在，则不采取任何行动。

代理将负责使用目录取消注册服务。 如果有关联的支票，那么也是注销。

方法	路径	产生
PUT	/agent/service/deregister/:service_id	application/json

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

阻止查询	一致性模式	ACL必需
NO	none	service:write

参数

• service_id (string: <required>) - 指定要注销的服务的ID。 这是URL的一部分。

Request Sample

$ curl \ --request PUT \ https://consul.rocks/v1/agent/service/deregister/my-service-id

»启用维护模式

该端点将给定的服务置于“维护模式”中。 在维护模式下，服务将被标记为不可用，不会出现在DNS或API查询中。 这个API调用是幂等的。 维护模式是持续的，并将在代理重新启动时自动恢复。

方法	路径	产生
PUT	/agent/service/maintenance/:service_id	application/json

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

阻止查询	一致性模式	ACL必需
NO	none	service:write

参数

• service_id (string: <required>) - 指定要进入维护模式的服务的ID。 这是URL的一部分。

• enable (bool: <required>) - 指定是启用还是禁用维护模式。 这是作为查询字符串参数的URL的一部分指定的。

• reason (string: "") - 指定一个文本字符串，说明将节点置于维护模式的原因。 这只是为了帮助人手。 如果没有提供任何理由，将使用默认值。 这是作为查询字符串参数的URL的一部分指定的，因此必须进行URI编码。

Request Sample

$ curl \ --request PUT \ https://consul.rocks/v1/agent/service/maintenance/my-service-id?enable=true&reason=For+the+docs

转载于:https://my.oschina.net/percylee/blog/1524602