IBM Cloud Docs
调用 IBM Cloud 服务 API

调用 IBM Cloud 服务 API

要授权应用程序和服务进行API调用,请将您的凭据传递给服务的API,以验证您的用户身份和访问权限,以便在服务范围内执行操作。

可以通过以下其中一种方式来识别调用者:

  • IBM Cloud Identity and Access Management (IAM) 令牌
  • IBM Cloud API 密钥或服务标识 API 密钥

IBM Cloud API 密钥服务标识 API 密钥和 IAM 令牌可唯一标识调用者的身份。 调用者身份是在 IBM Cloud 帐户中创建的 IBM Cloud 用户或服务标识。

API 密钥是由一长串随机字符或数字组成的凭证。 一个 IBM Cloud 身份可以拥有多个 API 密钥。 每个 API 密钥都可以单独进行管理;即,如果此 API 密钥仅由您的服务使用,那么您可以删除此 API 密钥而不中断其他某个组件。

您可以使用 API 密钥来登录到 IBM Cloud 命令行界面 (CLI)生成 IAM 令牌。 虽然建议不要将 API 密钥用于生产用途,但您还是可以将 API 密钥发送到 IBM Cloud 服务。

传递 IBM Cloud IAM 令牌以向服务 API 进行认证

要检索 IAM 访问令牌,API 客户机必须首先调用 IBM Cloud IAM API 以认证和检索该令牌。 IBM Cloud 服务API客户端的首选方式是使用 IBM Cloud API密钥获取IAM访问令牌。 作为 JSON Web 令牌实现的 IAM 访问令牌可用于多次调用接受 IAM 访问令牌作为认证方法的 IBM Cloud 服务。 由于 IAM 访问令牌通过非对称密钥进行数字签名,因此 IBM Cloud 服务无需调用任何外部服务就能验证 IAM 访问令牌。 这将显著提高调用 API 的性能。

![使用访问令牌通过服务 API 进行身份验证](images/tokenauth.svg "使用 API 密钥从 IAM 获取令牌,并将访问令牌传递给目标服务以验证凭证 "")

要使用访问令牌向服务的 API 进行认证,请完成以下步骤:

  1. 首先,创建 IBM Cloud API 密钥(如果尚未创建)。
  2. API 客户机的下一个步骤是检索 IAM 访问令牌,如通过 API 密钥获取 IAM 令牌中所述。
  3. 从响应中,抽取属性 access_token 以获取 IAM 访问令牌。expires_in 指示 IAM 访问令牌 access_token 到期前的秒数。 您可以使用相对时间值,也可以使用基于 UNIX时间的绝对时间戳 expiration
  4. 按照 RFC 6750第 2.1 节所述发送IAM访问令牌。 授权请求头字段

查看以下示例:

  1. 使用 HTTP 头 Authorization
  2. 在IAM访问令牌前加上 Bearer eyJhbGciOiJSUzI1Ng...
  3. 在 HTTP 报头中添加前缀IAM访问令牌:Authorization: Bearer eyJhbGciOiJSUzI1Ng...
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1Ng..."
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import <sdk_base_package>.ExampleService.v1.ExampleService;
...
String bearerToken = // ... obtain bearer token value ...

// Create the authenticator.
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator(bearerToken);

// Create the service instance.
ExampleService service = new ExampleService(authenticator);

// 'service' can now be used to invoke operations.
...
// Later, if your bearer token value expires, you can set a new one like this:
newToken = // ... obtain new bearer token value
authenticator.setBearerToken(newToken);
const ExampleServiceV1 = require('mysdk/example-service/v1');
const { BearerTokenAuthenticator } = require('mysdk/auth');

const authenticator = new BearerTokenAuthenticator({
  bearerToken: '<access-token>',
});

const myService = new ExampleServiceV1({
  authenticator,
});
...

// Later when the access token expires, the application must acquire
// a new access token, then set it on the authenticator.
// Subsequent request invocations will include the new access token.
authenticator.setBearerToken('<new-access-token>')
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator

authenticator = BearerTokenAuthenticator(<your_bearer_token>)
service = ExampleService(authenticator=authenticator)

# after getting a new access token...
service.get_authenticator().set_bearer_token('54321');
    import {
    "github.com/IBM/go-sdk-core/v5/core"
    "<appropriate-git-repo-url>/exampleservicev1"
}
...
// Create the authenticator.
bearerToken := // ... obtain bearer token value ...
authenticator := &core.BearerTokenAuthenticator{
    BearerToken: bearerToken,
}

// Create the service options struct.
options := &exampleservicev1.ExampleServiceV1Options{
    Authenticator: authenticator,
}

// Construct the service instance.
service := exampleservicev1.NewExampleServiceV1(options)

// 'service' can now be used to invoke operations.
...
// Later, if your bearer token value expires, you can set a new one like this:
newToken := // ... obtain new bearer token value
authenticator.BearerToken = newToken

将同一 IAM 访问令牌用于后续的 IBM Cloud 服务 API 调用,以实现最佳性能和可扩展性。

Java SDK 参考

Node SDK 参考

Python SDK 参考

Go SDK 参考

传递 IBM Cloud API 密钥以向服务 API 进行认证

API 客户机可以将 IBM Cloud API 密钥直接传递到目标服务的 API。 为此,请使用基本授权 HTTP 头将 apikey 关键字作为用户名,并将 IBM Cloud API 密钥作为密码发送到目标服务。

在所有将 API 密钥传递到服务 API 的情况下,建议将 API 密钥用于服务标识或与功能标识关联的用户 API 密钥,该功能标识仅分配有处理特定服务所需的访问级别。

目标服务 API 必须使用 IBM Cloud IAM 服务来检查 IBM Cloud API 密钥。 下图显示了三种 API 交互。 IBM Cloud API 密钥会传递到每个目标服务的 API,因此每个目标服务必须通过调用 IBM Cloud IAM 来查找 IBM Cloud API 密钥详细信息。

使用API密钥对服务API进行身份验证
将API密钥传递给目标服务,目标服务再将API密钥传递给IAM以验证凭证
将API密钥传递给目标服务,目标服务再将API密钥传递给IAM以验证凭证

使用 IBM Cloud API 密钥很方便,并且可以轻松发现新的 API 并快速试用原型。 但此方法需要您以可读格式将 IBM Cloud API 密钥发送到目标服务的 API,这会导致不必要地泄露 API 密钥。 此外,由于目标服务的 API 必须始终内省 API 密钥,因此这种方法的性能较低,所以建议不要用于生产工作负载。

要使用 API 密钥向服务的 API 进行认证,请完成以下步骤:

  1. 首先,创建 IBM Cloud API 密钥(如果尚未创建)。
  2. 将RFC 7617 中定义的 IBM Cloud API密钥作为 HTTP 标头“授权”发送。 将 apikey 用作用户名,将 API 密钥值用作密码。

例如,以下步骤假定 API 密钥为 0a1A2b3B4c5C6d7D8e9E:

  1. 将用户名 apikey 和API密钥(以冒号分隔)连接起来:apikey:0a1A2b3B4c5C6d7D8e9E
  2. 对字符串进行 Base64 编码:base64("apikey:0a1A2b3B4c5C6d7D8e9E") => YXBpa2V5OjBhMUEyYjNCNGM1QzZkN0Q4ZTlF
  3. 使用模式 Basic 来设置 HTTP 头 Authorization,例如 Authorization: Basic YXBpa2V5OjBhMUEyYjNCNGM1QzZkN0Q4ZTlF。 使用 curl 命令时,可以使用 -u 参数来传递此项:
curl -u "apikey:<IBM Cloud API key value>"
import com.ibm.cloud.sdk.core.security.BasicAuthenticator;
import <sdk_base_package>.ExampleService.v1.ExampleService;
...
// Create the authenticator.
BasicAuthenticator authenticator = new BasicAuthenticator.Builder()
    .username("myuser")
    .password("mypassword")
    .build();

// Create the service instance.
ExampleService service = new ExampleService(authenticator);

// 'service' can now be used to invoke operations.

from ibm_cloud_sdk_core.authenticators import BasicAuthenticator

authenticator = BasicAuthenticator(<your_username>, <your_password>)
service = ExampleService(authenticator=authenticator)
import {
    "github.com/IBM/go-sdk-core/v5/core"
    "<appropriate-git-repo-url>/exampleservicev1"
}
...
// Create the authenticator.
authenticator := &core.BasicAuthenticator{
    Username: "myuser",
    Password: "mypassword",
}

// Create the service options struct.
options := &exampleservicev1.ExampleServiceV1Options{
    Authenticator: authenticator,
}

// Construct the service instance.
service := exampleservicev1.NewExampleServiceV1(options)

// 'service' can now be used to invoke operations.

用户名为 apikey,密码为 API 密钥本身。