Apollo開放平臺 API

一、 什麼是開放平臺？

Apollo提供了一套的Http REST接口，使第三方應用能夠自己管理配置。雖然Apollo系統本身提供了Portal來管理配置，但是在有些情景下，應用需要通過程序去管理配置。

二、 第三方應用接入Apollo開放平臺

2.1 註冊第三方應用

第三方應用負責人需要向Apollo管理員提供一些第三方應用基本信息。

基本信息如下：

• 第三方應用的AppId、應用名、部門
• 第三方應用負責人

Apollo管理員在 http://{portal_address}/open/manage.html 創建第三方應用，創建之前最好先查詢此AppId是否已經創建。創建成功之後會生成一個token，如下圖所示：

[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳(img-n7gMFONd-1585386458792)(https://github.com/ctripcorp/apollo/raw/master/doc/images/apollo-open-manage.png)]

2.2 給已註冊的第三方應用授權

第三方應用不應該能操作任何Namespace的配置，所以需要給token綁定可以操作的Namespace。Apollo管理員在 http://{portal_address}/open/manage.html 頁面給token賦權。賦權之後，第三方應用就可以通過Apollo提供的Http REST接口來管理已授權的Namespace的配置了。

2.3 第三方應用調用Apollo Open API

2.3.1 調用Http REST接口

任何語言的第三方應用都可以調用Apollo的Open API，在調用接口時，需要設置注意以下兩點：

• Http Header中增加一個Authorization字段，字段值爲申請的token
• Http Header的Content-Type字段需要設置成application/json;charset=UTF-8

2.3.2 Java應用通過apollo-openapi調用Apollo Open API

從1.1.0版本開始，Apollo提供了apollo-openapi客戶端，所以Java語言的第三方應用可以更方便地調用Apollo Open API。

首先引入apollo-openapi依賴：

<dependency>
    <groupId>com.ctrip.framework.apollo</groupId>
    <artifactId>apollo-openapi</artifactId>
    <version>1.1.0</version>
</dependency>

在程序中構造ApolloOpenApiClient：

String portalUrl = "http://localhost:8070"; // portal url
String token = "e16e5cd903fd0c97a116c873b448544b9d086de9"; // 申請的token
ApolloOpenApiClient client = ApolloOpenApiClient.newBuilder()
                                                .withPortalUrl(portalUrl)
                                                .withToken(token)
                                                .build();

後續就可以通過ApolloOpenApiClient的接口直接操作Apollo Open API了，接口說明參見下面的Rest接口文檔。

2.3.3 .Net core應用調用Apollo Open API

.Net core也提供了open api的客戶端，詳見https://github.com/ctripcorp/apollo.net/pull/77

三、 接口文檔

3.1 URL路徑參數說明

參數名	參數說明
env	所管理的配置環境
appId	所管理的配置AppId
clusterName	所管理的配置集羣名， 一般情況下傳入 default 即可。如果是特殊集羣，傳入相應集羣的名稱即可
namespaceName	所管理的Namespace的名稱，如果是非properties格式，需要加上後綴名，如sample.yml

3.2 API接口列表

3.2.1 獲取App的環境，集羣信息

• URL : http://{portal_address}/openapi/v1/apps/{appId}/envclusters
• Method : GET
• Request Params : 無
• 返回值Sample：

[
    {
        "env":"FAT",
        "clusters":[ //集羣列表
            "default",
            "FAT381"
        ]
    },
    {
        "env":"UAT",
        "clusters":[
            "default"
        ]
    },
    {
        "env":"PRO",
        "clusters":[
            "default",
            "SHAOY",
            "SHAJQ"
        ]
    }
]

3.2.2 獲取集羣下所有Namespace信息接口

• URL : http://{portal_address}/openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces
• Method: GET
• Request Params: 無
• 返回值Sample:

[
  {
    "appId": "100003171",
    "clusterName": "default",
    "namespaceName": "application",
    "comment": "default app namespace",
    "format": "properties", //Namespace格式可能取值爲：properties、xml、json、yml、yaml
    "isPublic": false, //是否爲公共的Namespace
    "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,
    "items": [
      {
        "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 獲取某個Namespace信息接口

• URL ： http://{portal_address}/openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}
• Method ： GET
• Request Params ：無
• 返回值Sample ：

{
    "appId": "100003171",
    "clusterName": "default",
    "namespaceName": "application",
    "comment": "default app namespace",
    "format": "properties", //Namespace格式可能取值爲：properties、xml、json、yml、yaml
    "isPublic": false, //是否爲公共的Namespace
    "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 創建Namespace

可以通過此接口創建Namespace，調用此接口需要授予第三方APP，APP級別的權限。

• URL ： http://{portal_address} /openapi/v1/apps/{appId}/appnamespaces
• Method ： POST
• Request Params ：無
• 請求內容(Request Body, JSON格式) ：

參數名	必選	類型	說明
name	true	String	Namespace的名字
appId	true	String	Namespace所屬的AppId
format	true	String	Namespace的格式，只能是以下類型： properties、xml、json、yml、yaml
isPublic	true	boolean	是否是公共文件
comment	false	String	Namespace說明
dataChangeCreatedBy	true	String	namespace的創建人，格式爲域賬號，也就是sso系統的User ID

• 返回值 Sample ：

 {
  "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所屬的部門}.${傳入的name值} ，例如調用接口傳入的name=xy-z, format=properties，應用的部門爲框架（FX）,那麼name=FX.xy-z

如果不是properties文件 name = ${appId所屬的部門}.${傳入的name值}.${format}，例如調用接口傳入的name=xy-z, format=json，應用的部門爲框架（FX）,那麼name=FX.xy-z.json

3.2.5 獲取某個Namespace當前編輯人接口

Apollo在生產環境（PRO）有限制規則：每次發佈只能有一個人編輯配置，且該次發佈的人不能是該次發佈的編輯人。 也就是說如果一個用戶A修改了某個namespace的配置，那麼在這個namespace發佈前，只能由A修改，其它用戶無法修改。同時，該用戶A無法發佈自己修改的配置，必須找另一個有發佈權限的人操作。 這個接口就是用來獲取當前namespace是否有人鎖定的接口。在非生產環境（FAT、UAT），該接口始終返回沒有人鎖定。

• URL ： http://{portal_address}/openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/lock
• Method ： GET
• Request Params ：無
• 返回值 Sample（未鎖定） ：

  {
  "namespaceName": "application",
  "isLocked": false
}

• 返回值Sample(被鎖定) ：

  {
  "namespaceName": "application",
  "isLocked": true,
  "lockedBy": "song_s" //鎖owner
}

3.2.6 新增配置接口

• URL ： http://{portal_address}/openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items
• Method ： POST
• Request Params ：無
• 請求內容(Request Body, JSON格式) ：

參數名	必選	類型	說明
key	true	String	配置的key，長度不能超過128個字符。非properties格式，key固定爲content
value	true	String	配置的value，長度不能超過20000個字符，非properties格式，value爲文件全部內容
comment	false	String	配置的備註,長度不能超過1024個字符
dataChangeCreatedBy	true	String	item的創建人，格式爲域賬號，也就是sso系統的User ID

• Request body sample :

{
    "key":"timeout",
    "value":"3000",
    "comment":"超時時間",
    "dataChangeCreatedBy":"zhanglea"
}

• 返回值Sample ：

  {
    "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}
• Method ： PUT
• Request Params ：無
• 請求內容(Request Body, JSON格式) ：

參數名	必選	類型	說明
key	true	String	配置的key，需和url中的key值一致。非properties格式，key固定爲content
value	true	String	配置的value，長度不能超過20000個字符，非properties格式，value爲文件全部內容
comment	false	String	配置的備註,長度不能超過1024個字符
dataChangeLastModifiedBy	true	String	item的修改人，格式爲域賬號，也就是sso系統的User ID

• Request body sample :

{
    "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}
• Method ： DELETE
• Request Params ：

參數名	必選	類型	說明
key	true	String	配置的key。非properties格式，key固定爲content
operator	true	String	刪除配置的操作者，域賬號

• 返回值 ： 無

3.2.9 發佈配置接口

• URL ： http://{portal_address}/openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/releases
• Method ： POST
• Request Params ：無
• Request Body ：

參數名	必選	類型	說明
releaseTitle	true	String	此次發佈的標題，長度不能超過64個字符
releaseComment	false	String	發佈的備註，長度不能超過256個字符
releasedBy	true	String	發佈人，域賬號，注意：如果ApolloConfigDB.ServerConfig中的namespace.lock.switch設置爲true的話（默認是false），那麼該環境不允許發佈人和編輯人爲同一人。所以如果編輯人是zhanglea，發佈人就不能再是zhanglea。

• Request Body example ：

{
    "releaseTitle":"2016-08-11",
    "releaseComment":"修改timeout值",
    "releasedBy":"zhanglea"
}

• 返回值Sample ：

{
    "appId": "test-0620-01",
    "clusterName": "test",
    "namespaceName": "application",
    "name": "2016-08-11",
    "configurations": {
        "timeout": "3000",
    },
    "comment": "修改timeout值",
    "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
• Method ： GET
• Request Params ：無
• 返回值Sample ：

{
    "appId": "test-0620-01",
    "clusterName": "test",
    "namespaceName": "application",
    "name": "2016-08-11",
    "configurations": {
        "timeout": "3000",
    },
    "comment": "修改timeout值",
    "dataChangeCreatedBy": "zhanglea",
    "dataChangeLastModifiedBy": "zhanglea",
    "dataChangeCreatedTime": "2016-08-11T14:03:46.232+0800",
    "dataChangeLastModifiedTime": "2016-08-11T14:03:46.235+0800"
}

四、錯誤碼說明

正常情況下，接口返回的Http狀態碼是200，下面列舉了Apollo會返回的非200錯誤碼說明。

4.1 400 - Bad Request

客戶端傳入參數的錯誤，如操作人不存在，namespace不存在等等，客戶端需要根據提示信息檢查對應的參數是否正確。

4.2 401 - Unauthorized

接口傳入的token非法或者已過期，客戶端需要檢查token是否傳入正確。

4.3 403 - Forbidden

接口要訪問的資源未得到授權，比如只授權了對A應用下Namespace的管理權限，但是卻嘗試管理B應用下的配置。

4.3 404 - Not Found

接口要訪問的資源不存在，一般是URL或URL的參數錯誤。

4.4 405 - Method Not Allowed

接口訪問的Method不正確，比如應該使用POST的接口使用了GET訪問等，客戶端需要檢查接口訪問方式是否正確。

4.4 500 - Internal Server Error

其它類型的錯誤默認都會返回500，對這類錯誤如果應用無法根據提示信息找到原因的話，可以找Apollo研發團隊一起排查問題。