API调试及自助排错

1. 概述

API控制台支持对已发布API进行调试，而在调试过程中遇到问题时，如何理解报错信息并快速定位和解决问题。本文将结合API调试页面提供的自助排错能力进行介绍。

2. 调试信息获取错误信息

所有的API请求只要到达网关，网关就会返回请求结果信息。用户可以查看返回结果的头部，即Header部分，来获取API网关返回的信息。其中X-Ca开头的属性均为API网关返回，其中您需要重点关注的信息为：

• X-Ca-Error-Code。API网关系统错误码，当请求出现错误被网关拦截后，由API网关提供的错误码。

• X-Ca-Request-Id。请求唯一ID，请求一旦进入API网关应用后，API网关就会生成请求ID并通过响应头返回给客户端，建议客户端与后端服务都记录此请求ID，可用于问题排查与跟踪。

• X-Ca-Error-Message。API网关返回的错误消息，当请求出现错误时API网关会通过响应头将错误消息返回给客户端。

2.1. 根据X-Ca-Request-Id查询更多调用信息

在应答的Header中获得X-Ca-Error-Code与X-Ca-Error-Message可以基本明确报错原因，而X-Ca-Request-Id可以用于在日志服务中查询请求日志、通过控制台查询结果、或提供给支持人员进行日志排查。

控制台查询步骤如下：

1. 登录API网关控制台。

2. 在左侧栏单击API调用——自助排错，输入API所在Region以及X-Ca-Request-Id，单击查询，就可以看到对应的日志信息。

2.1.1. API网关报错

当本次API网关调用响应信息中API网关错误码（X-Ca-Error-Code）不为空，说明本次调用被API网关拦截。错误码由一个6位长度的字符描述。当请求被API网关拦截时，API网关会返回相应的错误信息，并附有简单的错误原因说明（X-Ca-Error-Message），可以根据该部分内容排查错误原因。更多错误码解释请参考错误代码表。

2.1.2. 后端服务报错

当本次调用的HTTP状态码不为200，且API网关错误码为空，则表示本次调用API网关成功将请求转发到后端服务，后端服务经过处理后返回非200的状态码。这时候需要检查后端服务业务逻辑。如果是通过云市场购买的API，则需要咨询云市场的服务提供商。

2.1.3. 请求成功

当的本次调用返回的HTTP状态码为200，则表示本次请求API网关成功转发请求到后端服务，并且后端服务返回成功的应答。

3. 获取Trace日志

在API调试页面发送请求后。可以在Trace日志中可以查看API网关收到的请求、API网关的处理详情、API网关发给后端服务的请求、API网关收到的应答、API网关给客户端返回的应答。

如果使用的是子账号或者角色扮演账号，发送请求前需要勾选记录Trace日志，则需要确保使用的账号被主账号授予了当前API所在实例的AcquireGatewayToken接口RAM权限。示例如下，更多详情可以参考使用 RAM 管理 API。

{
 "Version": "1",
 "Statement": [
 {
 "Effect": "ALLOW",
 "Action": "apigateway:AcquireGatewayToken",
 "Resource": "acs:apigateway:{#regionId}:{#accountId}:instance/{#InstanceId}"
 }
 ]
}
# 其中{#}为变量标识，需要替换为实际值。

4. 使用自助排错分析错误原因

自助排错中的问题诊断展示了本次调用的部分日志数据，当调用出现失败的情况时，可以根据该部分的信息定位和排查问题。这里介绍部分字段用于快速定位出错位置：

• TotalLatency：API网关从接收到客户端请求，到完成客户端响应的总时间

• ServiceLatency：API网关向后端服务发送请求，到接收完后端服务响应的时间

通过上述两个字段可以快速分析出报错位置，当ServiceLatency为0则表示请求在API网关被拦截，未到达后端服务；当ServiceLatency不为0则表示请求到达后端服务。另外，整个请求链路的IO时间点也记录在日志中：

• FrontRequestStart：API网关开始接收到客户端请求的时间点

• FrontRequestEnd：API网关完成接收客户端请求的时间点

• BackendRequestStart：API网关开始向后端服务发起请求的时间点

• BackendRequestEnd：API网关完成向后端服务发起请求的时间点

• BackendResponseStart：API网关开始接收到后端服务响应的时间点

• BackendResponseEnd：API网关完成接收后端服务响应的时间点

• FrontResponseStart：API网关开始向客户端发送响应的时间点

• FrontResponseEnd：API网关完成向客户端发送响应的时间点

利用好请求日志信息能快速解决调用问题，详细的日志字段含义请参考通过日志服务查看API调用日志。