华为云用户手册

请求参数 表1 ListObjectsInput 参数名称 参数类型 是否必选 描述 Bucket string 必选 参数解释： 桶名。 约束限制： 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。 桶命名规则如下： 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。 禁止使用IP地址。 禁止以“-”或“.”开头及结尾。 禁止两个“.”相邻（如：“my..bucket”）。 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。 取值范围： 长度为3～63个字符。 默认取值： 无 Marker string 可选 参数解释： 列举桶内对象列表时，指定一个标识符，从该标识符以后按对象名的字典顺序返回对象列表。 约束限制： 仅用于非多版本列举。 取值范围： 长度大于0且不超过1024的字符串。 默认取值： 无 Prefix string 可选 参数解释： 限定返回的对象名必须带有指定前缀。 例如，假设您拥有以下对象：logs/day1、logs/day2、logs/day3和ExampleObject.jpg。如果您将logs/指定为前缀，将返回以字符串“logs/”开头的三个对象。如果您指定空的前缀且请求中没有其他过滤条件，将返回桶中的所有对象。 约束限制： 无 取值范围： 长度大于0且不超过1024的字符串。 默认取值： 无 MaxKeys number 可选 参数解释： 列举对象的最大数目，返回的对象列表将是按照字典顺序的最多前MaxKeys个对象。 约束限制： 无 取值范围： 1~1000，当超出范围时，按照默认的1000进行处理。 默认取值： 1000 Delimiter string 可选 参数解释： 对象名按照此标识符进行分组。通常与prefix参数搭配使用，如果指定了prefix，从prefix到第一次出现delimiter间具有相同字符串的对象名会被分成一组，形成一条CommonPrefixes；如果没有指定prefix，从对象名的首字符到第一次出现delimiter间具有相同字符串的对象名会被分成一组，形成一条CommonPrefixes。 例如，桶中有3个对象，分别为abcd、abcde、bbcde。如果指定delimiter为d，prefix为a，abcd、abcde会被分成一组，形成一条前缀为abcd的CommonPrefixes；如果只指定delimiter为d，abcd、abcde会被分成一组，形成一条前缀为abcd的CommonPrefixes，而bbcde会被单独分成一组，形成一条前缀为bbcd的CommonPrefixes。 对于并行文件系统，不携带此参数时默认列举是递归列举此目录下所有内容，会列举子目录。在大数据场景下（目录层级深、目录下文件多）的列举，建议设置[delimiter=/]，只列举当前目录下的内容，不列举子目录，提高列举效率。 约束限制： 无 取值范围： 长度大于0且不超过1024的字符串。 默认取值： 无 EncodingType string 可选 参数解释： 对响应中的部分元素进行指定类型的编码。如果Delimiter、Marker、Prefix、CommonPrefixes、NextMarker和Key包含xml 1.0标准不支持的控制字符（特殊字符），需设置该参数为url编码。 约束限制： 无 取值范围： 可选值为url。 默认取值： 无，不设置则不编码。

请求参数 表1 请求参数列表 参数名称 参数类型 是否必选 描述 Bucket string 必选 参数解释： 桶名。 约束限制： 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。 桶命名规则如下： 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。 禁止使用IP地址。 禁止以“-”或“.”开头及结尾。 禁止两个“.”相邻（如：“my..bucket”）。 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。 取值范围： 长度为3～63个字符。 默认取值： 无 Key string 必选 参数解释： 对象名。对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径，路径中不包含桶名。 例如，您对象的访问地址为examplebucket.obs.cn-north-4.myhuaweicloud.com/folder/test.txt 中，对象名为folder/test.txt。 约束限制： ObsClient.restoreObject中指定的对象必须是归档存储类别，否则调用该接口会报错。 取值范围： 长度大于0且不超过1024的字符串。 默认取值： 无 VersionId string 可选 参数解释： 待恢复归档存储或深度归档对象的版本号。 约束限制： 无 取值范围： 长度为32的字符串。 默认取值： 无，如果不设置则默认指定最新版本的对象。 Days number 必选 参数解释： 恢复对象后，会生成一个对象的标准存储副本，此参数指定恢复有效期，即标准存储副本的保存时间。 约束限制： 无 取值范围： [1, 30]，单位：天。 默认取值： 无 Tier RestoreTierType 可选 参数解释： 恢复选项，用户可根据需求选择恢复选项，不同的恢复选项恢复耗时不同。 约束限制： 无 取值范围： 恢复选项可选值详见RestoreTierType。 默认取值： Standard 表2 RestoreTierType 常量名 原始值 说明 ObsClient.enums.RestoreTierExpedited Expedited 快速恢复，归档存储恢复耗时1~5 min，深度归档（受限公测）存储恢复约耗时3~5 h。 ObsClient.enums.RestoreTierStandard Standard 标准恢复，归档存储恢复耗时3~5 h，深度归档（受限公测）存储恢复约耗时5~12 h。 说明： 对于深度归档对象，大批量恢复建议使用标准恢复，且对象最终恢复时间受对象大小以及取回数据量的影响。

接口约束 您必须是桶拥有者或拥有恢复归档或深度归档存储对象的权限，才能恢复归档或深度归档存储对象。建议使用 IAM 或桶策略进行授权，如果使用IAM则需授予obs:object:RestoreObject权限，如果使用桶策略则需授予RestoreObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。 重复恢复归档或深度归档存储对象时在延长恢复有效期的同时，也将会对恢复时产生的恢复费用进行重复收取。产生的标准存储类别的对象副本有效期将会延长，并且收取延长时间段产生的标准存储副本费用。

返回结果 表3 返回结果 参数类型 描述 表4 说明： 该接口返回是一个Promise类型，需要使用Promise、async/await语法处理。 参数解释： 接口返回信息，详见表4。 表4 Response 参数名称 参数类型 描述 CommonMsg ICommonMsg 参数解释： 接口调用完成后的公共信息，包含HTTP状态码，操作失败的错误码等，详见ICommonMsg。 InterfaceResult 表6 参数解释： 操作成功后的结果数据，详见表6。 约束限制： 当Status大于300时为空。 表5 ICommonMsg 参数名称 参数类型 描述 Status number 参数解释： OBS服务端返回的HTTP状态码。 取值范围： 状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。完整的状态码列表请参见状态码。 Code string 参数解释： OBS服务端返回的错误码。 Message string 参数解释： OBS服务端返回的错误描述。 HostId string 参数解释： OBS服务端返回的请求服务端ID。 RequestId string 参数解释： OBS服务端返回的请求ID。 Id2 string 参数解释： OBS服务端返回的请求ID2。 Indicator string 参数解释： OBS服务端返回的详细错误码。 表6 BaseResponseOutput 参数名称 参数类型 描述 RequestId string 参数解释： OBS服务端返回的请求ID。

返回结果 表2 返回结果 参数类型 描述 表3 说明： 该接口返回是一个Promise类型，需要使用Promise、async/await语法处理。 参数解释： 接口返回信息，详见表3。 表3 Response 参数名称 参数类型 描述 CommonMsg ICommonMsg 参数解释： 接口调用完成后的公共信息，包含HTTP状态码，操作失败的错误码等，详见ICommonMsg。 InterfaceResult 表5 参数解释： 操作成功后的结果数据，详见表5。 约束限制： 当Status大于300时为空。 表4 ICommonMsg 参数名称 参数类型 描述 Status number 参数解释： OBS服务端返回的HTTP状态码。 取值范围： 状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。完整的状态码列表请参见状态码。 Code string 参数解释： OBS服务端返回的错误码。 Message string 参数解释： OBS服务端返回的错误描述。 HostId string 参数解释： OBS服务端返回的请求服务端ID。 RequestId string 参数解释： OBS服务端返回的请求ID。 Id2 string 参数解释： OBS服务端返回的请求ID2。 Indicator string 参数解释： OBS服务端返回的详细错误码。 表5 GetObjectOutput 参数名称 参数类型 描述 RequestId string 参数解释： OBS服务端返回的请求ID。 DeleteMarker string 参数解释： 标识删除的对象是否是删除标记。 LastModified string 参数解释： 对象的最近一次修改时间。 ContentLength string 参数解释： 对象数据的长度。 CacheControl string 参数解释： 响应中的Cache-Control头。 ContentDisposition string 参数解释： 响应中的Content-Disposition头。 ContentEncoding string 参数解释： 响应中的Content-Encoding头 ContentLanguage string 参数解释： 响应中的Content-Language头 ContentType string 参数解释： 对象的MIME类型。 Expires string 参数解释： 响应中的Expires头。 ETag string 参数解释： 对象的ETag值。 VersionId string 参数解释： 对象的版本号。 WebsiteRedirectLocation string 参数解释： 当桶设置了Website配置，该参数指明对象的重定向地址。 StorageClass string 参数解释： 对象的存储类型，当对象存储类型是标准存储时，该值为空。 Restore string 参数解释： 归档存储类型对象的恢复状态。 Expiration string 参数解释： 对象的详细过期信息。 Content string | stream.Readable 参数解释： 对象的内容。当设置了SaveAsFile时该值为空；当设置了SaveAsStream且为true时该值为stream.Readable对象；当SaveAsFile和SaveAsStream都未设置时为Buffer对象。 Metadata object 参数解释： 对象自定义元数据。需要在桶的CORS配置中增加允许响应中可返回的附加头域。例如，新增x-amz-meta-property1以获取自定义元数据property1。

接口约束 您必须是桶拥有者或拥有下载对象的权限，才能下载对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:GetObject权限，如果使用桶策略则需授予GetObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。 对于存储类别为归档存储或深度归档存储的图片对象，需要确认对象的状态为“已恢复”才能对其进行下载和处理。

接口约束 您必须是桶拥有者或拥有设置对象元数据的权限，才能设置对象元数据。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:ModifyObjectMetaData权限，如果使用桶策略则需授予ModifyObjectMetaData权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。 当桶开启多版本控制时，最新版本的对象支持设置元数据，历史版本的对象不支持设置元数据。 对于存储类别为归档或深度归档存储的对象，不能对其设置对象的元数据。

接口约束 您必须是桶拥有者或拥有下载对象的权限，才能下载对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:GetObject权限，如果使用桶策略则需授予GetObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。 对于存储类别为归档存储或深度归档存储的对象，需要确认对象的状态为“已恢复”才能对其进行下载。

返回结果 表2 返回结果 参数类型 描述 表3 说明： 该接口返回是一个Promise类型，需要使用Promise、async/await语法处理。 参数解释： 接口返回信息，详见表3。 表3 Response 参数名称 参数类型 描述 CommonMsg ICommonMsg 参数解释： 接口调用完成后的公共信息，包含HTTP状态码，操作失败的错误码等，详见ICommonMsg。 InterfaceResult 表5 参数解释： 操作成功后的结果数据，详见表5。 约束限制： 当Status大于300时为空。 表4 ICommonMsg 参数名称 参数类型 描述 Status number 参数解释： OBS服务端返回的HTTP状态码。 取值范围： 状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。完整的状态码列表请参见状态码。 Code string 参数解释： OBS服务端返回的错误码。 Message string 参数解释： OBS服务端返回的错误描述。 HostId string 参数解释： OBS服务端返回的请求服务端ID。 RequestId string 参数解释： OBS服务端返回的请求ID。 Id2 string 参数解释： OBS服务端返回的请求ID2。 Indicator string 参数解释： OBS服务端返回的详细错误码。 表5 GetObjectOutput 参数名称 参数类型 描述 RequestId string 参数解释： OBS服务端返回的请求ID。 DeleteMarker string 参数解释： 标识删除的对象是否是删除标记。 LastModified string 参数解释： 对象的最近一次修改时间。 ContentLength string 参数解释： 对象数据的长度。 CacheControl string 参数解释： 响应中的Cache-Control头。 ContentDisposition string 参数解释： 响应中的Content-Disposition头。 ContentEncoding string 参数解释： 响应中的Content-Encoding头 ContentLanguage string 参数解释： 响应中的Content-Language头 ContentType string 参数解释： 对象的MIME类型。 Expires string 参数解释： 响应中的Expires头。 ETag string 参数解释： 对象的ETag值。 VersionId string 参数解释： 对象的版本号。 WebsiteRedirectLocation string 参数解释： 当桶设置了Website配置，该参数指明对象的重定向地址。 StorageClass string 参数解释： 对象的存储类型，当对象存储类型是标准存储时，该值为空。 Restore string 参数解释： 归档存储类型对象的恢复状态。 Expiration string 参数解释： 对象的详细过期信息。 Content string | stream.Readable 参数解释： 对象的内容。当设置了SaveAsFile时该值为空；当设置了SaveAsStream且为true时该值为stream.Readable对象；当SaveAsFile和SaveAsStream都未设置时为Buffer对象。 Metadata object 参数解释： 对象自定义元数据。需要在桶的CORS配置中增加允许响应中可返回的附加头域。例如，新增x-amz-meta-property1以获取自定义元数据property1。

返回结果 表2 返回结果 参数类型 描述 表3 说明： 该接口返回是一个Promise类型，需要使用Promise、async/await语法处理。 参数解释： 接口返回信息，详见表3。 表3 Response 参数名称 参数类型 描述 CommonMsg ICommonMsg 参数解释： 接口调用完成后的公共信息，包含HTTP状态码，操作失败的错误码等，详见ICommonMsg。 InterfaceResult 表5 参数解释： 操作成功后的结果数据，详见表5。 约束限制： 当Status大于300时为空。 表4 ICommonMsg 参数名称 参数类型 描述 Status number 参数解释： OBS服务端返回的HTTP状态码。 取值范围： 状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。完整的状态码列表请参见状态码。 Code string 参数解释： OBS服务端返回的错误码。 Message string 参数解释： OBS服务端返回的错误描述。 HostId string 参数解释： OBS服务端返回的请求服务端ID。 RequestId string 参数解释： OBS服务端返回的请求ID。 Id2 string 参数解释： OBS服务端返回的请求ID2。 Indicator string 参数解释： OBS服务端返回的详细错误码。 表5 BaseResponseOutput 参数名称 参数类型 描述 RequestId string 参数解释： OBS服务端返回的请求ID。

请求参数 表1 BucketRequestInput 参数名称 参数类型 是否必选 描述 Bucket string 必选 参数解释： 桶名。 约束限制： 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。 桶命名规则如下： 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。 禁止使用IP地址。 禁止以“-”或“.”开头及结尾。 禁止两个“.”相邻（如：“my..bucket”）。 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。 取值范围： 长度为3～63个字符。 默认取值： 无

接口约束 您必须是桶拥有者或拥有删除桶标签的权限，才能删除桶标签。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:bucket:DeleteBucketTagging权限，如果使用桶策略则需授予DeleteBucketTagging权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、自定义创建桶策略。 OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。

兼容性 版本修订记录信息：ChangeLog。 推荐使用的Node.js版本：Node 0.12.x，Node4.x，Node6.x，Node8.x，Node10.x。 接口函数：与旧版本（2.1.x）不完全兼容，接口变化如下表： 接口函数 变化说明 ObsClient.listBuckets 响应结果中InterfaceResult.Buckets字段变为数组，去掉InterfaceResult.Buckets.Bucket字段。 ObsClient.setBucketAcl 请求参数中Grants字段变为数组，去掉Grants.Grant字段。 ObsClient.getBucketAcl 响应结果中InterfaceResult.Grants字段变为数组，去掉InterfaceResult.Grants.Grant字段。 ObsClient.setObjectAcl 请求参数中Grants字段变为数组，去掉Grants.Grant字段。 ObsClient.getObjectAcl 响应结果中InterfaceResult.Grants字段变为数组，去掉InterfaceResult.Grants.Grant字段。 ObsClient.setBucketLogging 请求参数中LoggingEnabled.TargetGrants字段变为数组，去掉LoggingEnabled.TargetGrants.Grant字段。 ObsClient.getBucketLogging 响应结果中InterfaceResult.LoggingEnabled.TargetGrants字段变为数组，去掉InterfaceResult.LoggingEnabled.TargetGrants.Grant字段。 ObsClient.setBucketWebsite 请求参数中RoutingRules字段变为数组，去掉RoutingRules.RoutingRule字段。 ObsClient.getBucketWebsite 响应结果中InterfaceResult.RoutingRules字段变为数组，去掉InterfaceResult.RoutingRules.RoutingRule字段。 ObsClient.setBucketCors 请求参数中CorsRule字段改名为CorsRules。 ObsClient.getBucketCors 响应结果中InterfaceResult.CorsRule字段改名为InterfaceResult.CorsRules。 ObsClient.setBucketTagging 请求参数中TagSet字段改名为Tags并变为数组，去掉TagSet.Tag字段。 ObsClient.getBucketTagging 响应结果中InterfaceResult.TagSet字段改名为Tags并变为数组，去掉InterfaceResult.TagSet.Tag字段。

请求消息头 附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。 如下公共消息头需要添加到请求中。 名称 描述 是否必选 备注 Content-Type 消息体的类型（格式） 是 默认取值为“application/json”，有其他取值时会在具体接口中专门说明。 X-Auth-Token 用户Token 否 用户Token也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。 X-Project-ID 子项目ID 否 在多项目场景中使用 X-Domain-ID 帐号ID - - 公有云API同时支持使用AK/SK认证，AK/SK认证是使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。 AK/SK认证的详细说明请参加AK/SK认证。 对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加消息头后的请求如下所示。 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokensContent-Type: application/json

请求消息体 请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。 每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。 对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中username为用户名，domainname为用户所属的帐号名称，********为用户登录密码，xxxxxxxxxx为project的名称，如cn-north-1，您可以从终端节点中获取。 scope参数定义了Token的作用域，下面示例中获取的Token仅能访问project下的资源。您还可以设置Token额作用域为某个帐号下所有资源或帐号的某个project下的资源，详细定义请参见获取用户Token。 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokensContent-Type: application/json { "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "********", "domain": { "name": "domainname" } } } }, "scope": { "project": { "name": "xxxxxxxx" } } } } 到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x-subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

请求URI 尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。 请求URI由四部分构成：{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string} 参数 说明 URI-scheme 表示用于传输请求的协议，当前所有API均采用HTTPS协议。 Endpoint 指定承载REST服务端点的服务器 域名 或IP，不同服务不同区域的Endpoint不同，您可以从终端节点中获取。 例如，IAM服务在华北-北京一区域的Endpoint为iam.cn-north-1.myhuaweicloud.com。 resource-path 资源路径，即API访问路径，从具体API的URI模块获取。例如，获取用户Token接口的resource-path为/v3/auth/tokens。 query-string 查询参数，是可选部分，并不是每个API都有查询参数。查询参数前面需要带一个？，形式为参数名=参数取值。例如，limit=10表示查询不超过10条数据。 例如，您需要获取IAM在“华北-北京一”区域的Token，则需使用“华北-北京一”区域的Endpoint（iam.cn-north-1.myhuaweicloud.com），并在获取用户Token的URI部分找到resource-path（/v3/auth/tokens），拼接起来如下所示。 https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens 图1 URI示意图 为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求方法 HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。 请求方法 说明 GET 请求服务器返回指定资源。 PUT 请求服务器更新指定资源。 POST 请求服务器新增资源或执行特殊操作。 DELETE 请求服务器删除指定资源，如删除对象等。 HEAD 请求服务器资源头部。 PATCH 请求服务器更新资源的部分内容。 当资源不存在的时候，PATCH可能会去创建一个新的资源。 在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为： POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

响应消息体 响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。 对于获取用户Token接口，返回如下消息体。为篇幅起见，这里只展示部分内容。 { "token": { "expires_at": "2019-02-13T06:52:13.855000Z", "methods": [ "password" ], "catalog": [ { "endpoints": [ { "region_id": "cn-north-1",...... 当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。 { "error_msg": "The format of message is error", "error_code": "AS.0001" } 其中，error_code表示错误码，error_msg表示错误描述信息。

状态码 表1 状态码 状态码 编码 错误码说明 100 Continue 继续请求。 这个临时响应用来通知客户端，它的部分请求已经被服务器接收，且仍未被拒绝。 101 Switching Protocols 切换协议。只能切换到更高级的协议。 例如，切换到HTTP的新版本协议。 201 Created 创建类的请求完全成功。 202 Accepted 已经接受请求，但未处理完成。 203 Non-Authoritative Information 非授权信息，请求成功。 204 NoContent 请求完全成功，同时HTTP响应不包含响应体。 在响应OPTIONS方法的HTTP请求时返回此状态码。 205 Reset Content 重置内容，服务器处理成功。 206 Partial Content 服务器成功处理了部分GET请求。 300 Multiple Choices 多种选择。请求的资源可包括多个位置，相应可返回一个资源特征与地址的列表用于用户终端（例如：浏览器）选择。 301 Moved Permanently 永久移动，请求的资源已被永久的移动到新的URI，返回信息会包括新的URI。 302 Found 资源被临时移动。 303 See Other 查看其它地址。 使用GET和POST请求查看。 304 Not Modified 所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。 305 Use Proxy 所请求的资源必须通过代理访问。 306 Unused 已经被废弃的HTTP状态码。 400 BadRequest 非法请求。 建议直接修改该请求，不要重试该请求。 401 Unauthorized 在客户端提供认证信息后，返回该状态码，表明服务端指出客户端所提供的认证信息不正确或非法。 402 Payment Required 保留请求。 403 Forbidden 请求被拒绝访问。 返回该状态码，表明请求能够到达服务端，且服务端能够理解用户请求，但是拒绝做更多的事情，因为该请求被设置为拒绝访问，建议直接修改该请求，不要重试该请求。 404 NotFound 所请求的资源不存在。 建议直接修改该请求，不要重试该请求。 405 MethodNotAllowed 请求中带有该资源不支持的方法。 建议直接修改该请求，不要重试该请求。 406 Not Acceptable 服务器无法根据客户端请求的内容特性完成请求。 407 Proxy Authentication Required 请求要求代理的身份认证，与401类似，但请求者应当使用代理进行授权。 408 Request Time-out 服务器等候请求时发生超时。 客户端可以随时再次提交该请求而无需进行任何更改。 409 Conflict 服务器在完成请求时发生冲突。 返回该状态码，表明客户端尝试创建的资源已经存在，或者由于冲突请求的更新操作不能被完成。 410 Gone 客户端请求的资源已经不存在。 返回该状态码，表明请求的资源已被永久删除。 411 Length Required 服务器无法处理客户端发送的不带Content-Length的请求信息。 412 Precondition Failed 未满足前提条件，服务器未满足请求者在请求中设置的其中一个前提条件。 413 Request Entity Too Large 由于请求的实体过大，服务器无法处理，因此拒绝请求。为防止客户端的连续请求，服务器可能会关闭连接。如果只是服务器暂时无法处理，则会包含一个Retry-After的响应信息。 414 Request-URI Too Large 请求的URI过长（URI通常为网址），服务器无法处理。 415 Unsupported Media Type 服务器无法处理请求附带的媒体格式。 416 Requested range not satisfiable 客户端请求的范围无效。 417 Expectation Failed 服务器无法满足Expect的请求头信息。 422 UnprocessableEntity 请求格式正确，但是由于含有语义错误，无法响应。 429 TooManyRequests 表明请求超出了客户端访问频率的限制或者服务端接收到多于它能处理的请求。建议客户端读取相应的Retry-After首部，然后等待该首部指出的时间后再重试。 500 InternalServerError 表明服务端能被请求访问到，但是不能理解用户的请求。 501 Not Implemented 服务器不支持请求的功能，无法完成请求。 502 Bad Gateway 充当网关或代理的服务器，从远端服务器接收到了一个无效的请求。 503 ServiceUnavailable 被请求的服务无效。 建议直接修改该请求，不要重试该请求。 504 ServerTimeout 请求在给定的时间内无法完成。客户端仅在为请求指定超时（Timeout）参数时会得到该响应。 505 HTTP Version not supported 服务器不支持请求的HTTP协议的版本，无法完成处理。 父主题： 附录

约束与限制 当前章节的修复方式只支持新版本Agent，若Agent版本为老版本，建议先升级到新版本。 查看当前Agent版本的命令为： if [[ -f /usr/local/uniagent/extension/install/telescope/bin/telescope ]]; then /usr/local/uniagent/extension/install/telescope/bin/telescope -v; elif [[ -f /usr/local/telescope/bin/telescope ]]; then echo "old agent"; else echo 0; fi

约束与限制 当前章节的修复方式只支持新版本Agent，若Agent版本为老版本，建议先升级到新版本。 查看当前Agent版本的命令为： if [[ -f /usr/local/uniagent/extension/install/telescope/bin/telescope ]]; then /usr/local/uniagent/extension/install/telescope/bin/telescope -v; elif [[ -f /usr/local/telescope/bin/telescope ]]; then echo "old agent"; else echo 0; fi

操作步骤 使用root账号，登录Agent不上报数据的E CS 或BMS。 可选：执行以下命令，切换至Agent安装路径的bin下。 Windows系统下，路径为：“C:\Program Files\uniagent\extension\install\telescope\bin” Linux系统下， 路径为：/usr/local/uniagent/extension/install/telescope/bin 修改配置文件conf.json。 执行以下命令，打开配置文件conf.json。 vi conf.json 在conf.json文件中，添加如下四行参数，具体参数请参见表1。 表1 参数说明 参数 说明 cpu_first_pct_threshold 第一阈值（CPU），默认值为10，单位为%。 memory_first_threshold 第一阈值（内存），默认值为209715200（200MB），单位为Byte。 cpu_second_pct_threshold 第二阈值（CPU），默认值为30，单位为%。 memory_second_threshold 第二阈值（内存），默认值为734003200（700MB），单位为Byte。 aAgent的CPU使用率和内存使用率查询方法： Linux： top -p telescope的PID Windows： 在任务管理器中查看Agent进程详情。 { "cpu_first_pct_threshold": xx, "memory_first_threshold": xxx, "cpu_second_pct_threshold": xx, "memory_second_threshold": xxx} 执行如下命令，保存并退出conf.json文件。 :wq 请执行如下命令，重启Agent。 Windows系统下： 在Agent安装包存放目录下，先双击执行shutdown.bat脚本，停止Agent，再执行start.bat脚本，启动Agent。 Linux系统下: 执行以下命令查看Agent的PID。 ps -ef |grep telescope 强制关闭进程后等待3-5分钟agent可实现自动重启，操作示例如图1所示。 kill -9 PID 图1 重启Agent

约束与限制 当前章节的修复方式只支持新版本Agent，若Agent版本为老版本，建议先升级到新版本。 查看当前Agent版本的命令为： if [[ -f /usr/local/uniagent/extension/install/telescope/bin/telescope ]]; then /usr/local/uniagent/extension/install/telescope/bin/telescope -v; elif [[ -f /usr/local/telescope/bin/telescope ]]; then echo "old agent"; else echo 0; fi

Agent插件状态显示“故障”该如何处理？ 操作系统监控插件每1分钟发送1次心跳；当服务端3分钟收不到插件心跳时，“插件状态”显示为“故障”。 “故障”原因可能为： Agent域名无法解析，请先确认修改DNS与添加安全组中 DNS地址 配置正确，然后参考《 云监控服务 用户指南》中“手动配置Agent”章节检查配置是否正确。 账号欠费。 Agent进程故障，请参照管理Agent重启，如果无法重启则说明相关文件被误删，请重新安装Agent。 服务器内部时间和本地标准时间不一致。 Agent插件版本不同，日志路径也不同。 日志路径分别如下： Linux： 新版本Agent：/usr/local/uniagent/extension/install/telescope/log/ces.log 老版本Agent：/usr/local/telescope/log/ces.log Windows： 新版本Agent：C:\Program Files\uniagent\extension\install\telescope\log\ces.log 老版本Agent：C:\Program Files\telescope\log\ces.log 使用的DNS非华为云DNS，请通过执行dig+目标域名获取到agent.ces.myhuaweicloud.com在华为云内网DNS下解析到的IP后再添加对应的hosts。华为云提供的内网DNS地址请参见华为云提供的内网DNS地址是多少？。 父主题： 主机监控

问题解决（Linux） 以root用户登录弹性云服务器或裸金属服务器。 执行如下命令，检查telescope进程是否存在： ps -ef |grep telescope 当显示如下内容时，表示telescope进程正常。 图1 查看telescope进程 进程正常：请执行4。 进程异常：请执行3。 如果进程异常，执行如下命令，启动Agent。 service uniagent restart 执行如下命令，确认云服务器委托已创建。 curl -ivk https://agent.ces.myhuaweicloud.com/v1.0/agencies/cesagency/securitykey 当有数据返回时，表示获取AK/SK正常。排查结束。 调用失败或者回显如下时，请执行5。 图2 获取AK/SK失败 在管理控制台的 统一身份认证 服务页面，选择“委托”，查询“cesagency”委托，查看cesagency委托中“项目[所属区域]”是否包含当前区域，若不存在，单击“权限配置”，然后单击“配置权限”，搜索“ CES Administrator”，单击下拉框，勾选当前区域。 图3 查询cesagency委托 图4 配置权限 问题解决，排查结束。 未解决，请执行6。 执行如下命令，确认DNS解析是否正常。 ping agent.ces.myhuaweicloud.com 网络正常：排查结束。 网络无法访问：修改DNS配置或CES的终端节点。 各区域对应的 云监控 服务的Endpoint请参考“地区和终端节点”。

问题解决（Windows） 以administrator权限用户登录弹性云服务器或裸金属服务器。 进入任务管理器，查看telescope进程是否存在。 当包括图5和图6两个进程时，表示telescope进程正常。 图5 agent进程-Windows 图6 telescope进程-Windows 进程正常：请执行4。 进程异常：请执行3。 双击C:\Program Files\uniagent\script目录下的start.bat，启动Agent。 在管理控制台的统一身份认证服务页面，选择“委托”，查询“cesagency”委托，查看cesagency委托中“项目[所属区域]”是否包含当前区域，若不存在，单击“权限配置”，然后单击“配置权限”，搜索“CES Administrator”，单击下拉框，勾选当前区域。 图7 查询cesagency委托 图8 配置权限 问题解决，排查结束。 未解决，请执行6。 执行如下命令，确认DNS解析是否正常。 ping agent.ces.myhuaweicloud.com 网络正常：排查结束。 网络无法访问：修改DNS配置或CES的终端节点。 各区域对应的云监控服务的Endpoint请参考“地区和终端节点”。

约束与限制 当前章节的修复方式只支持新版本Agent，若Agent版本为老版本，建议先升级到新版本。 查看当前Agent版本的命令为： if [[ -f /usr/local/uniagent/extension/install/telescope/bin/telescope ]]; then /usr/local/uniagent/extension/install/telescope/bin/telescope -v; elif [[ -f /usr/local/telescope/bin/telescope ]]; then echo "old agent"; else echo 0; fi

问题解决（Windows） 以administrator权限用户登录弹性云服务器或裸金属服务器。 进入任务管理器，查看Agent进程是否存在。 当包括图5和图6两个进程时，表示Agent进程正常。 图5 agent进程-Windows 图6 telescope进程-Windows 进程正常：请执行4。 进程异常：请执行3。 双击start.bat，启动Agent。 访问http://169.254.169.254/openstack/latest/meta_data.json，确认云服务器委托已创建。 可访问：表示委托正常，排查结束。 不可访问：请执行6。 执行如下命令，检查路由： route print 当返回如下信息时，表示路由正常： 图7 路由配置正常-Windows 路由正常：排查结束。 路由异常：请执行7。 当路由不存在时，执行如下命令，添加路由： route add -host 169.254.169.254 gw 192.168.0.1 上述命令斜体部分192.168.0.1为云服务器的网关，请根据实际情况修改配置。 问题是否解决？ 解决：排查结束。 未解决：执行7。 打开Agent安装包存放目录bin/conf_ces.json配置文件。 获取Agent配置文件中的Endpoint。 {"Endpoint":"https://ces.cn-north-4.myhuaweicloud.com"} 执行如下命令，确认DNS解析是否正常。 ping ces.cn-north-4.myhuaweicloud.com 网络正常：排查结束。 网络无法访问：修改DNS配置或CES的终端节点。 各区域对应的云监控服务的Endpoint请参考“地区和终端节点”。

问题分析 弹性云服务器或裸金属服务器安装Agent后仍然无操作系统监控数据时，一般考虑有如下几个原因： Agent进程运行状态异常 委托异常 路由配置异常导致的获取临时AK/SK失败 网络问题 首先需要确认使用的Agent版本。 使用root账号，登录ECS。 执行如下命令，确认使用老版本Agent。 if [[ -f /usr/local/uniagent/extension/install/telescope/bin/telescope ]]; then /usr/local/uniagent/extension/install/telescope/bin/telescope -v; elif [[ -f /usr/local/telescope/bin/telescope ]]; then echo "old agent"; else echo 0; fi 返回“old agent”，表示使用老版本Agent。 返回版本号，表示使用新版本Agent。 返回“0”，表示未安装Agent。

常见4XX问题处理 HTTP状态码 400 错误码 ces.0014 可能原因 原因1：请求参数格式错误。详见下方【案例一】 原因2：必传字段没有传。详见下方【案例二】 案例一 请求参数格式错误 from、to属性对应的值应该换算为毫秒进行传参。 period属性支持的枚举值：1,300,1200,3600,14400,86400。 filter属性支持的枚举值：average,max,min,sum,variance。 请求参数 {"from": 1724331974, ##传参为秒级非毫秒级"to": 1724315493, ##传参为秒级非毫秒级"period": "10086", ##period属性对应的枚举值不存在10086"filter": "standard", ##filter属性对应的枚举值不存在standard"metrics": [{"dimensions": [{"name": "instance_id","value": "129718f5-833d-4f78-b685-6b1c3091ea69"}],"metric_name": "mem_usedPercent","namespace": "AGT.ECS"}]} 响应参数 {"http_code": 400,"message": {"details": "Some content in message body is not correct, error message: [from, to]",##from,to属性问题"code": "ces.0014"},"encoded_authorization_message": null} 案例二 必传字段没有传 filter必传字段没有传，更多必传字段请查询接口文档。 请求参数 {"from": 1724119607020,"to": 1724123207020,"period": "1","metrics": [{"dimensions": [{"name": "instance_id","value": "238764d4-c4e1-4274-88a1-5956b057766b"}],"metric_name": "mem_usedPercent","namespace": "AGT.ECS"}]} 响应参数 {"http_code": 400,"message": {"details": "Some content in message body is not correct, error message: [filter]", ##filter属性问题"code": "ces.0014"},"encoded_authorization_message": null} HTTP状态码 404 错误码 APIGW.0101 可能原因 原因1：路径的URI与接口文档不一致。详见下方【案例一】 案例一 路径的URI与接口文档不一致 请求路径中URI中的版本号写错，应该为V1.0非V1。正确URI为/V1.0/{project_id}/batch-query-metric-data。 请求路径 POST /V1/04f9aca88c00d3202fd4c01ed679daf0/batch-query-metric-data 响应参数 {"error_code": "APIGW.0101","error_msg": "The API does not exist or has not been published in the environment","request_id": "7d7a8258354300ac158c7b14a158d6ec"} HTTP状态码 401 错误码 ces.0015 可能原因 原因1：请求IAM 获取Token 中写的项目ID与调用批量查询监控数据接口接口使用的项目ID不同。 原因2：Token 过期。 原因3：Token内容复制过程少复制或多复制其他内容。 原因4：ak与sk不匹配。 定位思路 根据可能原因进行故障排查。 解决方法 原因1：请求IAM获取Token请求参数写的项目ID与调用批量查询监控数据接口使用的项目ID不同。 解决方法: 将获取Token请求参数中项目ID参数与调用批量查询监控数据接口使用的项目ID保存一致。 原因2：Token 过期。 解决方法: 重新生成Token。 原因3：Token内容复制过程少复制或多复制其他内容。 解决方法: 获取正确的Token。 原因4：ak与sk不匹配。 解决方法: 获取租户匹配的AK与SK。 案例 Token异常导致认证失败。 请求头 X-Auth-Token：MIIqDgYJKoZIhvcNAQcCoIIp-zCC......+6CIyAFrbHVxQZJ2Jq ##Token异常 请求参数 {"from": 1724311893283,"to": 1724315493283,"period": "1","filter": "average","metrics": [{"dimensions": [{"name": "instance_id","value": "129718f5-833d-4f78-b685-6b1c3091ea69"}],"metric_name": "mem_usedPercent","namespace": "AGT.ECS"}]} 响应参数 {"http_code": 401,"message": {"details": "Authenticate failed.","code": "ces.0015"},"encoded_authorization_message": null} HTTP状态码 403 错误码 ces.0050 可能原因 原因1：用户策略中没有ces:metricData:list细粒度权限。详见下方【案例一】 案例一 用户策略中没有ces:metricData:list细粒度权限 用户策略中没有 ces:metricData:list 细粒度权限。需要在用户所属策略中添加该action。 请求头 X-Auth-Token：MIIqDgYJKoZIhvcNAQcCoIIp-zCC......+6CIyAFrbHVxQZJ2Jq 请求参数 {"from": 1724311893283,"to": 1724315493283,"period": "1","filter": "average","metrics": [{"dimensions": [{"name": "instance_id","value": "129718f5-833d-4f78-b685-6b1c3091ea69"}],"metric_name": "mem_usedPercent","namespace": "AGT.ECS"}]} 响应参数 {"http_code": 403,"message": {"details": "Policy doesn't allow [ces:metricData:list] to be performed.", ##用户策略中没有 ces:metricData:list 细粒度权限"code": "ces.0050"},"encoded_authorization_message": null} HTTP状态码 429 错误码 ces.0429 可能原因 原因1：API被流控。详见下方【案例一】 案例一 API被流控 请求API被流控。 若API被流控，需第一时间找运维人员配置新的流程策略。 请求参数 {"from": 1724311893283,"to": 1724315493283,"period": "1","filter": "average","metrics": [{"dimensions": [{"name": "instance_id","value": "129718f5-833d-4f78-b685-6b1c3091ea69"}],"metric_name": "mem_usedPercent","namespace": "AGT.ECS"}]} 响应参数 {"http_code": 429,"message": {"details": "Too Many Requests.", "code": "ces.0429"},"encoded_authorization_message": null}