携程 apollo api

Apollo管理员在http：// {portal_address} /open/manage.html创建第三方应用，创建之前最好先查询此AppId是否已经创建。创建成功之后会生成一个令牌，如下图所示：

2.2给已注册的第三方应用授权

第三方应用不应该能操作任何Namespace的配置，所以需要给token绑定可以操作的Namespace.Apollo管理员在http：// {portal_address} /open/manage.html页面给token赋权。赋权之后，第三方应用就可以通过Apollo提供的Http REST接口来管理已授权的Namespace的配置了。

2.3第三方应用调用Http REST接口

第三方应用在调用接口时，需要设置注意以下两点：

• Http Header中增加一个授权字段，字段值为申请的令牌
• Http Header的Content-Type字段需要设置成application / json; charset = UTF-8

三，接口文档

3.1 URL路径参数说明

参数名	参数说明
ENV	所管理的配置环境
APPID	所管理的配置的AppId
CLUSTERNAME	所管理的配置集群名，一般情况下传入默认即可。如果是特殊集群，传入相应集群的名称即可
namespaceName	所管理的命名空间的名称

3.2 API接口列表

3.2.1获取App的环境，集群信息

• 网址：http：// {portal_address} / openapi / v1 / apps / {appId} / envclusters
• 方法：GET
• 请求参数：无
• 返回值示例：

[
    {
        “ env ”： “ FAT ”，
         “ clusters ”：[ //集群列表
            “ default ”，
             “ FAT381 ”
        ]
    }，
    {
        “ env ”： “ UAT ”，
         “群集”：[
             “默认”
        ]
    }，
    {
        “ env ”： “ PRO ”，
         “ cluster ”：[
             “ default ”，
             “ SHAOY ”，
             “ SHAJQ ”
        ]
    }
]

3.2.2获取集群下所有Namespace信息接口

• URL：http：// {portal_address} / openapi / v1 / envs / {env} / apps / {appId} / clusters / {clusterName} / namespaces
• 方法：GET
• 请求参数：无
• 返回值示例：

[
  {
    “ appId ”： “ 100003171 ”，
     “ clusterName ”： “ default ”，
     “ namespaceName ”： “ application ”，
     “ comment ”： “ default app namespace ”，
     “ format ”： “ properties ”， // Namespace格式可能取值为：properties，xml，json，yml，yaml
    “ isPublic ”：不对，//是否为公共的命名空间
    “ items ”：[ //  Namespace下所有的配置集合
      {
        “ key ”： “ batch ”，
         “ value ”： “ 100 ”，
         “ dataChangeCreatedBy ”： “ song_s ”，
         “ dataChangeLastModifiedBy ”： “ song_s ”，
         “ dataChangeCreatedTime ”： “ 2016-07-21T16：03：43.000 + 0800 ”，
         “ dataChangeLastModifiedTime ”：“ 2016-07-21T16：03：43.000 + 0800“
      }
    ]
    “ dataChangeCreatedBy ”： “ song_s ”，
     “ dataChangeLastModifiedBy ”： “ song_s ”，
     “ dataChangeCreatedTime ”： “ 2016-07-20T14：05：58.000 + 0800 ”，
     “ dataChangeLastModifiedTime ”： “ 2016-07-20T14：05：58.000 + 0800 “
  }，
  {
    “ appId ”： “ 100003171 ”，
     “ clusterName ”： “ default ”，
     “ namespaceName ”： “ FX.apollo ”，
     “ comment ”： “ apollo public namespace ”，
     “ format ”： “ properties ”，
     “ isPublic ”： true，
     “项目“：[
      {
        “ key ”： “ request.timeout ”，
         “ value ”： “ 3000 ”，
         “ comment ”： “ ”，
         “ dataChangeCreatedBy ”： “ song_s ”，
         “ dataChangeLastModifiedBy ”： “ song_s ”，
         “ dataChangeCreatedTime ”： “ 2016-07- 20T14：08：30。000 + 0800 “，
         ”dataChangeLastModifiedTime “：” 2016-08-01T13：56：25.000 + 0800 “
      }，
      {
        “ id ”： 1116，
         “ key ”： “ batch ”，
         “ value ”： “ 3000 ”，
         “ comment ”： “ ”，
         “ dataChangeCreatedBy ”： “ song_s ”，
         “ dataChangeLastModifiedBy ”： “ song_s ”，
         “dataChangeCreatedTime “： ”2016-07-28T15：13：42.000 + 0800 “，
         ” dataChangeLastModifiedTime “：” 2016-08-01T13：51：00.000 + 0800 “
      }
    ]
    “ dataChangeCreatedBy ”： “ song_s ”，
     “ dataChangeLastModifiedBy ”： “ song_s ”，
     “ dataChangeCreatedTime ”： “ 2016-07-20T14：08：13.000 + 0800 ”，
     “ dataChangeLastModifiedTime ”： “ 2016-07-20T14：08：13.000 + 0800 “
  }
]

3.2.3获取某个命名空间信息接口

• URL：http：// {portal_address} / openapi / v1 / envs / {env} / apps / {appId} / clusters / {clusterName} / namespaces / {namespaceName}
• 方法：GET
• 请求参数：无
• 返回值示例：

{
     “ appId ”：“ 100003171 ”，
     “ clusterName ”：“ default ”，
     “ namespaceName ”：“ application ”，
     “ comment ”：“ default app namespace ”，
     “ format ”：“ properties ”，// Namespace格式可能取值为：properties，xml，json，yml，yaml
    “ isPublic ”：假的，//是否为公共的命名空间
    “ items ”：[ //  Namespace下所有的配置集合
      {
        “ key ”： “ batch ”，
         “ value ”： “ 100 ”，
         “ dataChangeCreatedBy ”： “ song_s ”，
         “ dataChangeLastModifiedBy ”： “ song_s ”，
         “ dataChangeCreatedTime ”： “ 2016-07-21T16：03：43.000 + 0800 ”，
         “ dataChangeLastModifiedTime ”：“ 2016-07-21T16：03：43.000 + 0800“
      }
    ]
    “ dataChangeCreatedBy ”： “ song_s ”，
     “ dataChangeLastModifiedBy ”： “ song_s ”，
     “ dataChangeCreatedTime ”： “ 2016-07-20T14：05：58.000 + 0800 ”，
     “ dataChangeLastModifiedTime ”： “ 2016-07-20T14：05：58.000 + 0800 “
  }

3.2.4创建命名空间

可以通过此接口创建命名空间，调用此接口需要授予第三方APP，APP级别的权限。

• 网址：http：// {portal_address} / openapi / v1 / apps / {appId} / appnamespaces
• 方法：POST
• 请求参数：无
• 请求内容（Request Body，JSON格式）：

参数名	必选	类型	说明
名称	真正	串	命名空间的名字
APPID	真正	串	命名空间所属的的AppId
格式	真正	串	Namespace的格式，只能是以下类型：properties，xml，json，yml，yaml
isPublic	真正	布尔	是否是公共文件
评论	假	串	命名空间说明
dataChangeCreatedBy	真正	串	namespace的创建人，格式为域账号，也就是sso系统的用户名

• 返回值示例：

{
   “ name ”：“ FX.public-0420-11 ”，
   “ appId ”：“ 100003173 ”，
   “ format ”：“ properties ”，
   “ isPublic ”：true，
   “ comment ”：“ test ”，
   “ dataChangeCreatedBy ”：“ zhanglea “，
   ”dataChangeLastModifiedBy “：“ zhanglea ”，
   “ dataChangeCreatedTime ”： “ 2017-04-20T18：25：49.033 + 0800 ”，
   “ dataChangeLastModifiedTime ”： “ 2017-04-20T18：25：49.033 + 0800 ”
}

• 返回值说明：

如果是properties文件，name = $ {appId所属的部门}。$ {传入的名称值}，例如调用接口传入的名称= xy-z，format = properties，应用的部门为框架（FX），那么名称= FX.xy-Z

如果不是properties文件name = $ {appId所属的部门}。$ {传入的名称值}。$ {format}，例如调用接口传入的名称= xy-z，format = json，应用的部门为框架（ FX），那么名称= FX.xy-z.json

3.2.5获取某个Namespace当前编辑人接口

Apollo在生产环境（PRO）有限制规则：每次发布只能有一个人编辑配置，且该次发布的人不能是该次发布的编辑人。也就是说如果一个用户A修改了某个命名空间的配置，那么在这个命名空间发布前，只能由A修改，其它用户无法修改。同时，该用户A无法发布自己修改的配置，必须找另一个有发布权限的人操作。这个接口就是用来获取当前命名空间是否有人锁定的接口。在非生产环境（FAT，UAT），该接口始终返回没有人锁定。

• URL：http：// {portal_address} / openapi / v1 / envs / {env} / apps / {appId} / clusters / {clusterName} / namespaces / {namespaceName} / lock
• 方法：GET
• 请求参数：无
• 返回值Sample（未锁定）：

  {
   “ namespaceName ”：“ application ”，
   “ isLocked ”：false
}

• 返回值Sample（被锁定）：

  {
   “ namespaceName ”：“ application ”，
   “ isLocked ”：true，
   “ lockedBy ”：“ song_s ”  //锁所有者
}

3.2.6新增配置接口

• URL：http：// {portal_address} / openapi / v1 / envs / {env} / apps / {appId} / clusters / {clusterName} / namespaces / {namespaceName} / items
• 方法：POST
• 请求参数：无
• 请求内容（Request Body，JSON格式）：

参数名	必选	类型	说明
键	真正	串	配置的键，长度不能超过128个字符
值	真正	串	配置的值，长度不能超过20000个字符
评论	假	串	配置的备注，长度不能超过1024个字符
dataChangeCreatedBy	真正	串	item的创建人，格式为域账号，也就是sso系统的用户名

• 申请正文样本：

{
     “ key ”：“ timeout ”，
     “ value ”：“ 3000 ”，
     “ comment ”：“超时时间”，
     “ dataChangeCreatedBy ”：“ zhanglea ”
}

• 返回值示例：

  {
     “ key ”：“ timeout ”，
     “ value ”：“ 3000 ”，
     “ comment ”：“超时时间”，
     “ dataChangeCreatedBy ”：“ zhanglea ”，
     “ dataChangeLastModifiedBy ”：“ zhanglea ”，
     “ dataChangeCreatedTime ”：“2016-08-11T12：06：41.818 + 0800 “，
    “ dataChangeLastModifiedTime ”： “ 2016-08-11T12：06：41.818 + 0800 ”
}

3.2.7修改配置接口

• URL：http：// {portal_address} / openapi / v1 / envs / {env} / apps / {appId} / clusters / {clusterName} / namespaces / {namespaceName} / items / {key}
• 方法：PUT
• 请求参数：无
• 请求内容（Request Body，JSON格式）：

参数名	必选	类型	说明
键	真正	串	配置的关键，长度不能超过128个字符。需和网址中的关键值一致
值	真正	串	配置的值，长度不能超过20000个字符
评论	假	串	配置的备注，长度不能超过1024个字符
dataChangeLastModifiedBy	真正	串	item的修改人，格式为域账号，也就是sso系统的用户名

• 申请正文样本：

{
     “ key ”：“ timeout ”，
     “ value ”：“ 3000 ”，
     “ comment ”：“超时时间”，
     “ dataChangeLastModifiedBy ”：“ zhanglea ”
}

• 返回值：无

3.2.8删除配置接口

• URL：http：// {portal_address} / openapi / v1 / envs / {env} / apps / {appId} / clusters / {clusterName} / namespaces / {namespaceName} / items / {key}？operator = {operator}
• 方法：DELETE
• 请求参数：

参数名	必选	类型	说明
操作者	真正	串	删除配置的操作者，域账号

• 返回值：无

3.2.9发布配置接口

• URL：http：// {portal_address} / openapi / v1 / envs / {env} / apps / {appId} / clusters / {clusterName} / namespaces / {namespaceName} / releases
• 方法：POST
• 请求参数：无
• 申请机构：

参数名	必选	类型	说明
releaseTitle	真正	串	此次发布的标题，长度不能超过64个字符
releaseComment	假	串	发布的备注，长度不能超过256个字符
被释放	真正	串	发布人，域账号，注意：如果ApolloConfigDB.ServerConfig中的namespace.lock.switch设置为真实的话（默认是假的），那么该环境不允许发布人和编辑人为同一人所以如果编辑人是zhanglea，发布人就不能再是zhanglea。

• 请求正文示例：

{
     “ releaseTitle ”：“ 2016年8月11日”，
     “ releaseComment ”：“修改超时值”，
     “ releasedBy ”：“ zhanglea ”
}

• 返回值示例：

{
     “ appId ”：“ test-0620-01 ”，
     “ clusterName ”：“ test ”，
     “ namespaceName ”：“ application ”，
     “ name ”：“ 2016-08-11 ”，
     “ configurations ”：{
         “ timeout ”：“ 3000 ”，
    }，
    “ comment ”： “修改超时值”，
     “ dataChangeCreatedBy ”： “ zhanglea ”，
     “ dataChangeLastModifiedBy ”： “ zhanglea ”，
     “ dataChangeCreatedTime ”： “ 2016-08-11T14：03：46.232 + 0800 ”，
     “ dataChangeLastModifiedTime ”： “ 2016 -08-11T14：03：46.235 + 0800 “
}

3.2.10获取某个Namespace当前生效的已发布配置接口

• URL：http：// {portal_address} / openapi / v1 / envs / {env} / apps / {appId} / clusters / {clusterName} / namespaces / {namespaceName} / releases / latest
• 方法：GET
• 请求参数：无
• 返回值示例：

{
     “ appId ”：“ test-0620-01 ”，
     “ clusterName ”：“ test ”，
     “ namespaceName ”：“ application ”，
     “ name ”：“ 2016-08-11 ”，
     “ configurations ”：{
         “ timeout ”：“ 3000 ”，
    }，
    “ comment ”： “修改超时值”，
     “ dataChangeCreatedBy ”： “ zhanglea ”，
     “ dataChangeLastModifiedBy ”： “ zhanglea ”，
     “ dataChangeCreatedTime ”： “ 2016-08-11T14：03：46.232 + 0800 ”，
     “ dataChangeLastModifiedTime ”： “ 2016 -08-11T14：03：46.235 + 0800 “
}

四，错误码说明

正常情况下，接口返回的的Http状态码是200，下面列举了阿波罗会返回的非200错误码说明。

4.1 400 - 错误请求

客户端传入参数的错误，如操作人不存在，命名空间不存在等等，客户端需要根据提示信息检查对应的参数是否正确。

4.2 401 - 未经授权

接口传入的令牌非法或者已过期，客户端需要检查记号是否传入正确。

4.3 403 - 禁止

接口要访问的资源未得到授权，比如只授权了对甲应用下命名空间的管理权限，但是却尝试管理乙应用下的配置。

4.3 404 - 未找到

接口要访问的资源不存在，一般是URL或URL的参数错误。

4.4 405 - 不允许的方法

接口访问的方法不正确，比如应该使用POST的接口使用了GET访问等，客户端需要检查接口访问方式是否正确。

4.4 500 - 内部服务器错误

其它类型的错误默认都会返回500，对这类错误如果应用无法根据提示信息找到原因的话，可以找阿波罗研发团队一起排查问题。

 

来自