什么是 API 管理？

在架构或系统设计上下文中，API 管理通常指可配置、功能强大的反向代理，用于管理从客户端（外部、内部或其他方式）到 API、端点或方法的访问。 API 管理通常与 RESTful API（包括但不限于）一起使用，它提供了一个请求管理和保护层，用于验证、检查、更改和处理传入请求，并且可以进一步修改或处理从后端系统返回的响应。 一些组织可能会使用_企业服务总线_实现类似目标。 企业服务总线是一类技术的灵活定义术语，其中包含与该组件相关的其他含义，但可以从 API 管理服务的同一组建议中受益。

API 管理系统的示例包括以下系统和其他系统：

• Azure API 管理
• AWS API 网关
• Mulesoft Anypoint
• Apigee
• Kong
• Boomi

了解 API 管理

API 管理行为不同于传统的反向代理，后者通常将整个 HTTP 流量模式转发到后端服务器。 例如：

<外部主机>:443/server/rest/services/* » <内部主机>>:6443/arcgis/rest/services/*

API 管理通常涉及选择单独的 API URI 路径和 HTTP 方法（即为 /routes/extract 指定 POST，为 /routes/<routeid> 指定 PATCH），这意味着必须定义每个单独的方法或模式，而且每个模式可以具有不同的规则、行为和后端侦听器或服务。 这通常用于构建新的 API 或系统（不存在现有 Web 服务集），或启用微服务风格的架构，其中不同的后端组件或系统负责为单独的 API 请求提供服务。 在某些情况下，API 管理可能会使用后端 API 定义（如 OpenAPI 规范）来创建许多前端端点或方法。

API 管理通常还包括一系列其他处理选项，这些选项可以作请求内容（调整或重写路径、添加或修改标头、根据 POST 正文内容更改目标）、对请求应用一定程度的过滤（速率限制、阻止某些 IP 范围、需要 API 密钥）或对响应进行操作（模糊服务器名称、移除响应标头、添加指纹或标识符）。 这些操作在 API 管理层中定义，并在提交请求和创建响应时作用于每个请求。

所有这些模式通常也适用于企业服务总线技术，但有一些差异。 ESB 往往更专注于同步消息传递，其中某一部分的系统更改（添加新记录、进行更新）会触发将此更改推送到 ESB，然后 ESB 将消息转换并推送到其他系统以保持它们同步。 从某种意义上说，API 管理更像是一种查询和轮询方法，其中 ESB 经常引入强消息传递承诺、发布-订阅模式或其他类似方法。

API 管理和 ArcGIS

API 管理可以多种不同的模式与 ArcGIS 一起使用。 通常，API 管理_最适用于_将 API 管理部署在基于 ArcGIS Server 的服务（例如地图、要素或地理处理服务）的“前面”的用例，在这些用例中，这些服务需要公开给其他企业系统或使用自定义应用程序的开发人员或最终客户。 使用 API 管理的一些关键注意事项包括：

• API 管理通常最适合作为具有独立 ArcGIS Server 部署的架构模式。 对于 ArcGIS Enterprise 部署中的联合服务器，处理其所需的令牌交换和验证明显更为复杂，并且需要高级 ArcGIS 配置或 API 管理配置和知识才能处理各种身份验证请求和端点。
• ArcGIS REST 服务通常由 API 管理系统匿名访问，来自 API 管理“服务”的请求将发送到 ArcGIS 后端，无需进一步的身份验证步骤。 虽然 ArcGIS 支持多种身份验证模式，从内置用户名和密码到 SAML 和 OIDC，但 API 管理模式通常假定后端 API 可以匿名访问，以接收来自 API 管理服务的请求。
• API 管理通常用于公开特定服务或端点，而不是整个 ArcGIS Server 站点。 如果您的目标是公开整个站点，则通常建议选择传统的反向代理解决方案，它与工作流程更兼容。
• ArcGIS 通常提供更详细的 REST API，这意味着 API 管理服务必须支持灵活的通配符模式或仅支持转发特定路径。 如果目标是将服务公开给 ArcGIS 客户端软件，则这一点尤其重要，因为 ArcGIS 客户端软件在设计时即预设依赖完全可用的 API（可以访问所有方法和资源）。

例如：

• 转发此请求足以获取有关特定服务的详细信息：
  • /arcgis/rest/services/ServiceName/MapServer
• 但是，如果要支持地图服务功能和要素图层功能，则必须另外转发以下类型的请求：
  • /arcgis/rest/services/ServiceName/MapServer/exportImage
  • /arcgis/rest/services/ServiceName/MapServer/0/query
  • /arcgis/rest/services/ServiceName/MapServer/1/query

最佳做法

API 管理是一种越来越流行的方法，用于提供企业系统之间的集成选项。 许多组织投资或创建策略，以确保所有内部事务都由 API 管理系统代理，或者可能需要使用 API 管理来创建外部可访问的服务。 在系统集成上下文中，最佳实践包括：

• 如果目标是仅应用 API 管理服务级别的身份验证，并让所有用户活动都使用该端点，则定义为后端的 ArcGIS 服务通常应配置为不安全或“与所有人共享”，并通过网络设计或防火墙限制公共或组织访问，并且仅通过 API 管理服务启用访问权限。
• 考虑使用 Web 上下文 URL 和实施代理相关标头，确保 API 管理背后的 ArcGIS Server 组件知道代理并在可能的情况下返回有效 URL。
• 需要检查和修改通过 API 管理服务从请求返回的链接，才能使用正确的主机名和上下文来执行进一步的请求。 例如，异步打印服务请求返回生成的 PDF 输出的最终 URL，然后用户将请求该 URL，该 URL 可能引用内部主机名，并且可以在 API 管理系统中重写内容。

使用 API 密钥和身份验证

根据定义，API 管理不包括身份验证层，但许多组织希望将身份验证应用于其 API 管理端点，以进行用户验证和授权管理。 常见的 API 管理身份验证方法包括使用 API 或订阅密钥，以及与现有身份提供者 (IdP) 的基于 OAuth 的身份验证方法集成。 所有这些模式都会给 ArcGIS 集成工作流带来一些挑战。

请注意，基于 API 管理的客户端身份验证方法可能与标准 ArcGIS 客户端不兼容。 例如，如果 API 管理系统需要基于标头的身份验证，无论是使用特定于服务的标头还是 Bearer Authorization 标头，标准 ArcGIS 客户端将无法将该标头动态添加到请求中以支持访问该服务。 同样，API 密钥可能是通过 API 管理接口添加的常见身份验证层，但应用程序开发人员需要了解此要求，并能够将其添加到请求中，以便将这些服务集成到应用程序中。 各种 ArcGIS SDK 和服务注册模式都可以支持此类订阅密钥或 API 密钥身份验证模式，但在假设身份验证模式合适之前，应对其进行仔细测试。

对 API 管理进行基于 OAuth 的身份验证还带来了其他挑战。 使用受支持的 SDK 开发自定义应用程序时，相对简单的做法是提供对 OAuth 服务的初始重定向，返回令牌或代码，并使用该令牌追加到该会话中的更多请求。 但是，在使用 ArcGIS 现成应用程序时，此配置更难成功使用，因为这些客户端希望直接访问 ArcGIS 地理服务，而无需执行不由 ArcGIS 托管的其他身份验证步骤。

通常，在此上下文中使用 API 或订阅密钥可提供最成功的集成路径，并提供以下建议：

• API 密钥或订阅密钥必须支持用作 URL 查询参数。 某些工作流（例如基于 Esri Maps SDK 的自定义应用程序或基于 Python 的集成）可以支持基于标头的身份验证，但对于大多数现有界面，目前无法使用非 ArcGIS 身份验证标头。
• API 密钥可以添加到在最新版本的 ArcGIS Online 或 ArcGIS Enterprise 中创建的内容项目中，作为项目创建期间提供的自定义参数，或直接附加到与项目一起注册的 URL。 仔细测试这些选项，评估它们是否提供对请求内容的充分访问权限。
• 在 ArcGIS Pro 中使用受 API 密钥保护的服务时，从路径添加数据工作流也支持使用自定义参数。