所有文档

          百度智能门户 AIPAGE

          通用说明

          API 调用遵循 HTTP 协议,仅有「全局」一种区域,具体域名为 aipage.baidubce.com。 数据交换格式为 JSON,所有 request/response body 内容均采用 UTF-8 编码。

          实名认证

          使用 AIPAGE API 的用户需要实名认证,没有通过实名认证的可以前往百度智能云官网控制台中的安全认证下的实名认证中进行认证。 百度云提供个人认证企业认证两种认证方式,您可以根据实际情况选择一种进行认证。

          API认证机制

          所有API的安全认证一律采用Access Key与请求签名机制。 Access Key由Access Key ID和Secret Access Key组成,均为字符串。 对于每个HTTP请求,使用下面所描述的算法生成一个认证字符串。提交认证字符串放在Authorization头域里。服务端根据生成算法验证认证字符串的正确性。 认证字符串的格式为bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}

          • version是正整数。
          • timestamp是生成签名时的UTC时间。
          • expirationPeriodInSeconds表示签名有效期限。
          • signedHeaders是签名算法中涉及到的头域列表。头域名之间用分号(;)分隔,如host;x-bce-date。列表按照字典序排列。(本API签名仅使用host和x-bce-date两个header)
          • signature是256位签名的十六进制表示,由64个小写字母组成。

          当百度云接收到用户的请求后,系统将使用相同的SK和同样的认证机制生成认证字符串,并与用户请求中包含的认证字符串进行比对。如果认证字符串相同,系统认为用户拥有指定的操作权限,并执行相关操作;如果认证字符串不同,系统将忽略该操作并返回错误码。

          鉴权认证机制的详细内容请参见鉴权认证机制

          通信协议

          支持HTTP和HTTPS两种调用方式。为了提升数据的安全性,建议通过HTTPS调用。

          请求结构说明

          数据交换格式为JSON,所有request/response body内容均采用UTF-8编码。

          请求参数包括如下4种:

          参数类型 说明
          URI 通常用于指明操作实体,如:PUT /v{version}/site/{siteId}
          Query参数 URL中携带的请求参数,通常用来指明要对实体进行的动作
          HEADER 通过HTTP头域传入,如:x-bce-date
          RequestBody 通过JSON格式组织的请求数据体

          响应结构说明

          响应值分为两种形式:

          响应内容 说明
          HTTP STATUS CODE 如200,400,403,404等
          ResponseBody JSON格式组织的响应数据体

          API版本号

          参数 类型 参数位置 描述 是否必须
          version String URI参数 API版本号,当前值为1 必须

          幂等性

          当调用创建资源的接口时,如果遇到了请求超时或服务器内部错误,用户可能会尝试重发请求,导致资源的超量创建。这时用户可以通过clientToken参数避免创建出比预期要多的资源,即保证请求的幂等性。

          幂等性基于clientToken,clientToken是一个长度不超过64位的ASCII字符串,通常放在query string里,如http://aipage.baidubce.com/v1/site?clientToken=be31b98c-5e41-4838-9830-9be700de5a20

          如果用户使用同一个clientToken值调用创建接口,则服务端会返回相同的请求结果。因此用户在遇到错误进行重试的时候,可以通过提供相同的clientToken值,来确保只创建一个资源;如果用户提供了一个已经使用过的clientToken,但其他请求参数(包括queryString和requestBody)不同甚至url Path不同,则会返回IdempotentParameterMismatch的错误代码。

          clientToken的有效期为24小时,以服务端最后一次收到该clientToken为准。也就是说,如果客户端不断发送同一个clientToken,那么该clientToken将长期有效。

          日期与时间规范

          日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡需要日期时间表示的地方一律采用UTC时间,遵循ISO 8601,并做以下约束:

          • 表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日。
          • 表示时间一律采用hh:mm:ss方式,并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
          • 凡涉及日期和时间合并表示时,在两者中间加大写字母T,例如2014-06-01T23:00:10Z表示UTC时间2014年6月1日23点0分10秒。

          规范化字符串

          通常一个字符串中可以包含任何Unicode字符。在编程中这种灵活性会带来不少困扰。因此引入“规范字符串”的概念。一个规范字符串只包含百分号编码字符以及URI(Uniform Resource Identifier)非保留字符(Unreserved Characters)。 RFC 3986规定URI非保留字符包括以下字符:字母(A-Z,a-z)、数字(0-9)、连字号(-)、点号(.)、下划线(_)、波浪线(~)。

          将任意一个字符串转换为规范字符串的方式是:

          • 将字符串转换成UTF-8编码的字节流。
          • 保留所有URI非保留字符原样不变。
          • 对其余字节做一次RFC 3986中规定的百分号编码(Percent-Encoding),即一个%后面跟着两个表示该字节值的十六进制字母。字母一律采用大写形式。

          示例: 原字符串:this is an example for 测试, 对应的规范字符串:this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95

          服务域名

          区域 服务端点Endpoint 协议
          全局 aipage.baidubce.com HTTP and HTTPS

          公共请求头

          头域 说明 是否必须
          Authorization 包含Access Key与请求签名。具体请参考鉴权认证 必须
          Content-Type application/json; charset=utf-8 必须
          x-bce-date 该请求创建的时间,表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日。如果用户使用了标准的Date域,该头域可以不填。当两者同时存在时,以x-bce-date为准。 必须
          host 请求 host,签名时必须签名此 host header 必须

          公共响应头

          头域 说明
          Content-Type application/json; charset=utf-8
          x-bce-request-id 对应请求的requestId

          错误码格式

          当用户访问 API 出现错误时,会返回给用户相应的错误码和错误信息,便于定位问题,并做出适当的处理。请求发生错误时通过 Response Body 返回详细错误信息,遵循如下格式:

          参数名 类型 说明
          status_code Number 表示具体错误的错误码,与 HTTP 状态码相同。
          code String 表示具体错误类型。
          message String 有关该错误的详细说明。
          request_id String 导致该错误的requestId。

          例如:

          {
              "status_code": 403,
              "code":"IllegalRequestUrl",
              "message":"The requested url belongs to domain which is not under acceleration",
              "request_id":" 81d0b05f-5ad4-1f22-8068-d5c9de60a1d7"
          }

          公共错误码

          错误码 错误消息 HTTP状态码 描述
          AccessDenied Access denied. 403 Forbidden 无权限访问对应的资源。
          InappropriateJSON The JSON you provided was well-formed and valid, but not appropriate for this operation. 400 Bad Request 请求中的JSON格式正确,但语义上不符合要求。如缺少某个必需项,或者值类型不匹配等。出于兼容性考虑,对于所有无法识别的项应直接忽略,不应该返回这个错误。
          InternalError We encountered an internal error. Please try again. 500Internal Server Error 所有未定义的其他错误。在有明确对应的其他类型的错误时(包括通用的和服务自定义的)不应该使用。
          InvalidAccessKeyId The Access Key ID you provided does not exist in our records. 403 Forbidden Access Key ID不存在。
          InvalidHTTPAuthHeader The HTTP authorization header is invalid. Consult the service documentation for details. 400 Bad Request Authorization头域格式错误。
          InvalidHTTPRequest There was an error in the body of your HTTP request. 400 Bad Request HTTP body格式错误。例如不符合指定的Encoding等。
          InvalidURI Could not parse the specified URI. 400 Bad Request URI形式不正确。例如一些服务定义的关键词不匹配等。对于ID不匹配等问题,应定义更加具体的错误码,例如NoSuchKey。
          MalformedJSON The JSON you provided was not well-formed. 400 Bad Request JSON格式不合法。
          InvalidVersion The API version specified was invalid. 404 Not Found URI的版本号不合法。
          OptInRequired A subscription for the service is required. 403 Forbidden 没有开通对应的服务。
          PreconditionFailed The specified If-Match header doesn't match the ETag header. 412 Precondition Failed 详见ETag。
          RequestExpired Request has expired. Timestamp date is XXX. 400 Bad Request 请求超时。XXX要改成x-bce-date的值。如果请求中只有Date,则需要将Date转换为datetime。
          IdempotentParameterMismatch The request uses the same client token as a previous, but non-identical request. 403 Forbidden clientToken对应的API参数不一样。
          SignatureDoesNotMatch The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details. 400 Bad Request Authorization头域中附带的签名和服务端验证不一致。

          AIPAGE 错误码

          错误码 错误消息 HTTP状态码 描述
          IdempotentParameterMismatch 不同的请求使用了相同的幂等性 token 400 对于不同的请求需要使用不同的 cientToken,如果不同请求使用了相同的 token,则会报此错误,更换 clientToken 即可
          InvalidParameter 错误的参数,有具体错误参数的信息 400 请根据文档校验对应参数的限制并修改
          InvalidRoutes 不合法的路由地址 404 访问了不存在的 api 路径
          上一篇
          简介
          下一篇
          接口说明