身份验证、请求和响应Authentication, requests and responses

Azure Key Vault 支持 JSON 格式的请求和响应。Azure Key Vault supports JSON formatted requests and responses. Azure Key Vault 请求会与部分 URL 参数、JSON 编码的请求和响应正文一起定向到使用 HTTPS 的有效 Azure Key Vault URL。Requests to the Azure Key Vault are directed to a valid Azure Key Vault URL using HTTPS with some URL parameters and JSON encoded request and response bodies.

本主题介绍 Azure Key Vault 服务的详细信息。This topic covers specifics for the Azure Key Vault service. 有关使用 Azure REST 接口的常规信息,包括身份验证/授权和如何获取访问令牌,请参阅 Azure REST API 参考For general information on using Azure REST interfaces, including authentication/authorization and how to acquire an access token, see Azure REST API Reference.

请求 URLRequest URL

密钥管理操作使用 HTTP DELETE、GET、PATCH、PUT 和 HTTP POST,而针对现有密钥对象的加密操作则使用 HTTP POST。Key management operations use HTTP DELETE, GET, PATCH, PUT and HTTP POST and cryptographic operations against existing key objects use HTTP POST. 不支持特定 HTTP 谓词的客户端也可能使用 HTTP POST(使用 X-HTTP-REQUEST 标头)来指定所需谓词,通常不需要正文的请求在使用 HTTP POST 时应添加一个空的正文,比如使用 POST 而不是 DELETE 时。Clients that cannot support specific HTTP verbs may also use HTTP POST using the X-HTTP-REQUEST header to specify the intended verb; requests that do not normally require a body should include an empty body when using HTTP POST, for example when using POST instead of DELETE.

若要使用 Azure Key Vault 中的对象,请参考以下示例 URL:To work with objects in the Azure Key Vault, the following are example URLs:

  • 若要在 Key Vault 中创建名为 TESTKEY 的密钥,请使用 - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1To CREATE a key called TESTKEY in a Key Vault use - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

  • 若要在 Key Vault 中导入名为 IMPORTEDKEY 的密钥,请使用 - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1To IMPORT a key called IMPORTEDKEY into a Key Vault use - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

  • 若要获取 Key Vault 中名为 MYSECRET 的机密,请使用 - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1To GET a secret called MYSECRET in a Key Vault use - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

  • 若要在 Key Vault 中使用名为 TESTKEY 的密钥签名摘要,请使用 - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1To SIGN a digest using a key called TESTKEY in a Key Vault use - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

    对 Key Vault 请求的授权始终如下所示:https://{keyvault-name}.vault.azure.cn/The authority for a request to a Key Vault is always as follows, https://{keyvault-name}.vault.azure.cn/

    密钥始终存储在 /keys 路径下,机密始终存储在 /secrets 路径下。Keys are always stored under the /keys path, Secrets are always stored under the /secrets path.

API 版本API Version

Azure Key Vault 服务支持协议版本控制,可与下层客户端兼容,但并非所有功能都可供这些客户端使用。The Azure Key Vault Service supports protocol versioning to provide compatibility with down-level clients, although not all capabilities will be available to those clients. 客户端必须使用 api-version 查询字符串参数,指定无默认协议时支持的协议版本。Clients must use the api-version query string parameter to specify the version of the protocol that they support as there is no default.

Azure Key Vault 协议版本遵循使用 {YYYY}.{MM}.{DD} 格式的日期编号方案。Azure Key Vault protocol versions follow a date numbering scheme using a {YYYY}.{MM}.{DD} format.

请求正文Request Body

根据 HTTP 规范,GET 操作不得包含请求正文,而 POST 和 PUT 操作必须包含请求正文。As per the HTTP specification, GET operations must NOT have a request body, and POST and PUT operations must have a request body. DELETE 操作中的正文在 HTTP 中是可选的。The body in DELETE operations is optional in HTTP.

除非操作说明中另有说明,否则请求正文内容类型必须为 application/json,且必须包含与内容类型一致的序列化 JSON 对象。Unless otherwise noted in operation description, the request body content type must be application/json and must contain a serialized JSON object conformant to content type.

除非操作说明中另有说明,否则接受请求标头必须包含 application/json 媒体类型。Unless otherwise noted in operation description, the Accept request header must contain the application/json media type.

响应正文Response Body

除非操作说明中另有说明,否则成功和失败操作的响应正文内容类型需为 application/json 并包含详细的错误信息。Unless otherwise noted in operation description, the response body content type of both successful and failed operations will be application/json and contains detailed error information.

使用 HTTP POSTUsing HTTP POST

部分客户端可能无法使用某些 HTTP 谓词,例如 PATCH 或 DELETE。Some clients may not be able to use certain HTTP verbs, such as PATCH or DELETE. Azure Key Vault 支持使用 HTTP POST 作为这些客户端的替代方法,前提是客户端也包括“X-HTTP-METHOD”标头以指定原始 HTTP 谓词。Azure Key Vault supports HTTP POST as an alternative for these clients provided that the client also includes the “X-HTTP-METHOD” header to specific the original HTTP verb. 本文档中定义的每个 API 都记录了对 HTTP POST 的支持。Support for HTTP POST is noted for each of the API defined in this document.

错误响应Error Responses

错误处理将使用 HTTP 状态代码。Error handling will use HTTP status codes. 得到的结果通常为:Typical results are:

  • 2xx - 成功:用于常规操作。2xx – Success: Used for normal operation. 响应正文包含预期的结果The response body will contain the expected result

  • 3xx - 重定向:可能返回 304“未修改”以满足条件性 GET。3xx – Redirection: The 304 "Not Modified" may be returned to fulfill a conditional GET. 未来可能会使用其他 3xx 代码,以指示 DNS 和路径更改。Other 3xx codes may be used in the future to indicate DNS and path changes.

  • 4xx - 客户端错误:用于错误请求、缺少密钥、语法错误、参数无效、身份验证错误等。响应正文包含详细的错误说明。4xx – Client Error: Used for bad requests, missing keys, syntax errors, invalid parameters, authentication errors, etc. The response body will contain detailed error explanation.

  • 5xx - 服务器错误:用于内部服务器错误。5xx – Server Error: Used for internal server errors. 响应正文包含汇总的错误信息。The response body will contain summarized error information.

    该系统用于代理或防火墙后方。The system is designed to work behind a proxy or firewall. 因此,客户端可能会收到其他错误代码。Therefore, a client might receive other error codes.

    出现问题时,Azure Key Vault 也会在响应正文中返回错误信息。Azure Key Vault also returns error information in the response body when a problem occurs. 响应正文为 JSON 格式,且采用以下形式:The response body is JSON formatted and takes the form:


{  
  "error":  
  {  
    "code": "BadArgument",  
    "message":  

      "’Foo’ is not a valid argument for ‘type’."  
    }  
  }  
}  

身份验证Authentication

必须对所有 Azure Key Vault 请求进行身份验证。All requests to Azure Key Vault MUST be authenticated. Azure Key Vault 支持通过 OAuth2 [RFC6749] 获得的 Azure Active Directory 访问令牌。Azure Key Vault supports Azure Active Directory access tokens that may be obtained using OAuth2 [RFC6749].

若要详细了解如何注册应用程序和进行身份验证以使用 Azure Key Vault,请参阅通过 Azure AD 注册客户端应用程序For more information on registering your application and authenticating to use Azure Key Vault, see Register your client application with Azure AD.

必须使用 HTTP 授权标头向服务发送访问令牌:Access tokens must be sent to the service using the HTTP Authorization header:

PUT /keys/MYKEY?api-version=<api_version>  HTTP/1.1  
Authorization: Bearer <access_token>  

如果未提供访问令牌或服务未接受访问令牌,则会向客户端返回 HTTP 401 错误,其中包含WWW-Authenticate 标头,例如:When an access token is not supplied, or when a token is not accepted by the service, an HTTP 401 error will be returned to the client and will include the WWW-Authenticate header, for example:

401 Not Authorized  
WWW-Authenticate: Bearer authorization="…", resource="…"  

WWW-Authenticate 标头的参数为:The parameters on the WWW-Authenticate header are:

  • authorization:可用于获取请求访问令牌的 OAuth2 授权服务的地址。authorization: The address of the OAuth2 authorization service that may be used to obtain an access token for the request.

  • resource:要在授权请求中使用的资源 (https://vault.azure.cn) 的名称。resource: The name of the resource (https://vault.azure.cn) to use in the authorization request.