Apollo配置API：RESTful接口完整指南

你是否还在手动修改配置文件、重启服务来更新应用配置？是否遇到过多环境配置同步困难、配置更新不及时导致线上故障的问题？本文将带你全面掌握Apollo配置中心的RESTful API，通过简单的接口调用实现配置的自动化管理，让你轻松解决配置管理的痛点。读完本文后，你将能够：注册第三方应用并获取访问令牌、使用API进行配置的增删改查、实现配置的批量更新与发布，以及通过脚本自动化配置管理流程。

开放平台概述

Apollo开放平台提供了一套完整的HTTP REST接口，使第三方应用能够通过程序管理配置。虽然Apollo提供了Web门户（Portal）进行配置管理，但在自动化部署、批量配置更新等场景下，API接口能发挥更大的作用。通过API，你可以实现配置的自动生成、更新、发布，以及与CI/CD流程的无缝集成。

官方文档：docs/zh/portal/apollo-open-api-platform.md

第三方应用接入流程

注册第三方应用

第三方应用负责人需要向Apollo管理员提供应用基本信息，包括应用的AppId、名称、部门以及负责人信息。Apollo管理员在http://{portal_address}/open/add-consumer.html页面创建第三方应用，创建成功后会生成一个访问令牌（token）。

查看第三方应用

Apollo管理员可以在http://{portal_address}/open/manage.html页面查看所有已注册的第三方应用列表，并进行令牌管理、权限分配等操作。

令牌管理与赋权

创建第三方应用后，管理员需要为其生成令牌并分配权限。令牌是第三方应用调用API的身份凭证，必须妥善保管。同时，管理员需要为第三方应用授权可操作的Namespace，以确保配置管理的安全性。

API调用方式

HTTP请求头设置

调用Apollo Open API时，需要在HTTP请求头中设置以下信息：

• Authorization: 第三方应用的访问令牌
• Content-Type: 固定为application/json;charset=UTF-8

支持的调用方式

Apollo Open API支持多种编程语言和工具调用，包括：

• Java客户端：通过apollo-openapi依赖包调用
• Shell脚本：使用curl命令调用，项目提供了封装好的脚本工具
• 其他语言：直接调用HTTP接口

Shell脚本工具：scripts/openapi/bash/openapi.sh

使用示例：scripts/openapi/bash/openapi-usage-example.sh

核心API接口详解

命名空间管理

创建Namespace

URL: http://{portal_address}/openapi/v1/apps/{appId}/appnamespaces
Method: POST
请求体:

{
  "name": "sample-namespace",
  "appId": "test-app",
  "format": "properties",
  "isPublic": false,
  "comment": "创建示例Namespace",
  "dataChangeCreatedBy": "apollo-user"
}

获取Namespace信息

URL: http://{portal_address}/openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}
Method: GET

配置项管理

创建配置项

URL: http://{portal_address}/openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items
Method: POST
请求体:

{
  "key": "timeout",
  "value": "3000",
  "comment": "超时时间配置",
  "dataChangeCreatedBy": "apollo-user"
}

更新配置项

URL: http://{portal_address}/openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items/{key}
Method: PUT
请求体:

{
  "key": "timeout",
  "value": "5000",
  "comment": "更新超时时间为5秒",
  "dataChangeLastModifiedBy": "apollo-user"
}

配置发布

发布Namespace配置

URL: http://{portal_address}/openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/releases
Method: POST
请求体:

{
  "releaseTitle": "20230925-配置更新",
  "releaseComment": "更新超时时间配置",
  "releasedBy": "apollo-user"
}

Shell脚本调用示例

以下是使用项目提供的Shell脚本进行配置管理的示例：

# 导出环境变量
export APOLLO_PORTAL_ADDRESS=http://apollo-portal:8070
export APOLLO_OPENAPI_TOKEN=your-token-here
source openapi.sh

# 创建配置项
item_create DEV test-app default application timeout 3000 "超时时间配置" apollo-user

# 发布配置
namespace_release DEV test-app default application "配置发布" "更新超时时间" apollo-user

错误码说明

Apollo Open API返回的常见HTTP状态码：

• 200: 请求成功
• 400: 参数错误，请检查请求参数
• 401: 未授权，令牌无效或已过期
• 403: 权限不足，第三方应用无操作权限
• 404: 资源不存在，检查URL路径是否正确
• 500: 服务器内部错误，请联系Apollo管理员

最佳实践

1. 令牌安全：不要将令牌硬编码在代码中，建议通过环境变量注入
2. 权限最小化：为第三方应用分配最小必要权限
3. 操作审计：重要配置变更建议记录操作日志
4. 错误处理：API调用失败时，根据错误码进行重试或告警

总结

通过Apollo配置API，你可以轻松实现配置的自动化管理，摆脱手动操作的繁琐和低效。本文详细介绍了API的注册授权、核心接口、调用方式和最佳实践，帮助你快速上手。如需更详细的接口文档，可以参考官方提供的Open API平台说明。

官方API文档：docs/zh/portal/apollo-open-api-platform.md

掌握Apollo配置API，让你的配置管理更加高效、可靠，为应用的持续交付提供有力支持。