更新时间:2021-09-18 GMT+08:00
分享

接口使用方法

公有云API符合RESTful API设计理论。REST从资源的角度观察整个网络,分布在各处的资源由URI(Uniform Resource Identifier)确定,客户端的应用通过URL(Unified Resource Locator)获取资源。URL的一般格式为:https://Endpoint/uri。其中URL为资源路径,也即API访问的路径。

公有云接口采用HTTPS传输协议,请求/响应报文使用JSON报文,媒体类型表示为Application/json。

ModelArts提供REST(Representational State Transfer) API。

REST从资源的角度来观察整个网络,提供创建、查询、更新、删除等方法访问服务的资源。

REST API请求/响应对可以分为五个部分:

  • 请求URI
  • 请求消息头
  • 请求消息体
  • 响应消息头
  • 响应消息体

请求URI

  • URI格式

    {URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}

    尽管请求URI包含在请求消息头中,但大多数语言或框架都要求您从请求消息中单独传递它,所以在这单独拿出来强调。

  • URI中的参数说明,如表1所示。
    表1 参数说明

    参数名称

    参数说明

    URI-scheme

    表示用于传输请求的协议。

    Endpoint

    指定承载REST服务端点的服务器域名或IP,从地区和终端节点中获取。

    resource-path

    资源路径,也即API访问路径。从具体接口的URI模块获取,例如“v3/auth/tokens”。

    Query string

    可选参数,例如API版本或资源选择标准。

请求消息头

请求消息头包含如下两部分:

  1. HTTP方法,告诉服务正在请求什么类型的操作。
    表2 HTTP方法

    方法

    说明

    GET

    请求服务器返回指定资源。

    PUT

    请求服务器更新指定资源。

    POST

    请求服务器新增资源或执行特殊操作。

    DELETE

    请求服务器删除指定资源,如删除对象等。

    HEAD

    请求服务器资源头部。

    PATCH

    请求服务器更新资源的部分内容。

    当资源不存在的时候,PATCH可能会去创建一个新的资源。

  2. 可选的附加请求头字段,如指定的URI和HTTP方法所要求的字段。详细的公共请求消息头字段,请参见表3。其中请求认证信息请参见获取请求认证
    表3 公共请求消息头

    名称

    说明

    Content-Type

    消息体的类型(格式)。

    必须字段。

    示例:application/json

    X-Auth-Token

    Token认证信息,通过Token认证获取。

    当使用Token方式认证时,必须填充该字段。

    X-Sdk-Date

    请求发送的时间。

    当使用AK/SK认证时,必须填充该字段。

    示例:20151222T034042Z

    Authorization

    签名认证信息,参数值来源于请求签名结果。

    当使用AK/SK认证时,必须填充该字段。

    示例:SDK-HMACSHA256

    Credential=ZIRRK

    MTWPTQFQI1WK

    NKB/20151222/cnnorth-

    1/ec2/

    sdk_request,

    SignedHeaders=con

    nection;contenttype;

    host;x-sdk-date,

    Signature=7972cc91

    45876d174b386218

    8a0f61819431fa71c

    8a8a060809ea8b898

    e3eaa9

    Host:

    www.myhwclouds.c

    om

请求消息体

请求消息体通常以结构化格式(如JSON格式)发出,与请求消息头中“Content-type”对应,传递除请求消息头之外的内容。

若请求消息体中参数支持中文,则中文字符必须为UTF-8编码。

响应消息头

响应消息头包含如下两部分:

  1. 一个HTTP状态代码,从2xx成功代码到4xx或5xx错误代码。 或者可以返回服务定义的状态码。
  2. 附加响应头字段,如支持请求的响应所需,如“Content-type”的响应消息头。详细的公共响应消息头字段,请参见表4
    表4 响应消息头

    名称

    说明

    Date

    HTTPS协议标准报头。表示消息发送的时间,时间的描述格式由rfc822定义。

    示例:Mon, 12 Nov 2007 15:55:01 GMT

    Server

    HTTPS协议标准报头。包含了服务器用来处理请求的软件信息。

    示例:Apache

    Content-Length

    HTTPS协议标准报头。用于指明实体正文的长度,以字节方式存储的十进制数字来表示。

    Content-Type

    HTTPS协议标准报头。用于指明发送给接收者的实体正文的媒体类型。

    示例:application/json

响应消息体

响应消息体通常以结构化格式(如JSON格式)返回,与响应消息头中“Content-type”对应,传递除响应消息头之外的内容。

发起请求

共有三种方式可以基于已构建好的请求消息发起请求,分别为:

  • cURL

    cURL是一个命令行工具,用来执行各种URL操作和信息传输。cURL充当的是HTTP客户端,可以发送HTTP请求给服务端,并接收响应消息。cURL适用于接口调试。关于cURL详细信息请参见https://curl.haxx.se/

  • 编码

    通过编码调用接口,组装请求消息,并发送处理请求消息。

  • REST客户端

    Mozilla、Google都为REST提供了图形化的浏览器插件,发送处理请求消息。针对Firefox,请参见Firefox RESTClient。针对Chrome,请参见Chrome RESTClient

分享:

    相关文档

    相关产品

关闭导读