Node.js V2.0 SDK泛化调用_阿里云SDK(Alibaba Cloud SDK)-阿里云帮助中心

阿里云SDK支持一种通用的方式调用OpenAPI，此方式被称为泛化调用。本文将为您详细介绍如何使用泛化调用访问OpenAPI。

特点

轻量：仅需安装阿里云核心SDK，无需额外安装云产品SDK。

简单：只需构造通用的请求参数对象，然后利用通用请求客户端调用通用函数发起请求，调用结果也以通用格式返回。

更多介绍，请参见泛化调用与特化调用。

使用说明

使用泛化调用时，建议先查看OpenAPI元数据，获取OpenAPI的API风格、请求参数、资源路径等信息。

安装核心SDK

在Terminal中执行以下命令安装核心SDK。

npm install @alicloud/openapi-client

调用OpenAPI

初始化请求客户端

通过创建client对象初始化请求客户端，并通过该client发起OpenAPI调用。在初始化客户端时，也支持使用Credentials工具，关于Credentials工具的更多信息，请参见管理访问凭证。

Node.js

// 从环境变量中获取阿里云访问密钥ID和密钥Secret。
let config = new OpenApi.Config({
    accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
    accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
});
config.endpoint = `ecs-cn-hangzhou.aliyuncs.com`;
let client = new OpenApi.default(config);


// 不指定参数，默认凭据链
// const credentialClient = new Credential.default();
// let config = new OpenApi.Config({
//     credential: credentialClient,
// });
// config.endpoint = `ecs-cn-hangzhou.aliyuncs.com`;
// let client = new OpenApi.default(config);

Typescript

// 从环境变量中获取阿里云访问密钥ID和密钥Secret。
let config = new $OpenApi.Config({
      accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
      accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
    });
config.endpoint = `ecs-cn-hangzhou.aliyuncs.com`;
let client = new OpenApi(config);

// 不指定参数，默认凭据链
// let credential = new Credential();
// let config = new $OpenApi.Config({
//   credential: credential,
// });
// config.endpoint = `ecs.cn-hangzhou.aliyuncs.com`;
// let client = new OpenApi(config)

配置OpenAPI信息

通过OpenApi.Params配置OpenAPI的基本信息，比如OpenAPI的风格、API版本、请求方式等信息。以调用DescribeInstanceTypeFamilies接口为例：

Node.js

// 配置OpenAPI信息
let params = new OpenApi.Params({
    style: 'RPC', // API风格：RPC或ROA
    action: 'DescribeInstanceTypeFamilies', // API 名称
    version: '2014-05-26', // API版本号
    protocol: 'HTTPS', // 请求协议：HTTPS或HTTP，建议使用HTTPS。
    method: 'POST', // 请求方法
    authType: 'AK', // 认证类型，默认即可。当OpenAPI支持匿名请求时，您可以传入 Anonymous 发起匿名请求。
    pathname: `/`, // API资源路径，RPC接口默认"/"，ROA接口从OpenAPI元数据中data.path获取资源路径。
    reqBodyType: 'json', // 接口请求体内容格式
    bodyType: 'json', // 接口响应体内容格式
});

Typescript

// 配置OpenAPI信息
let params = new $OpenApi.Params({
      style: 'RPC', // API风格：RPC或ROA
      action: 'DescribeInstanceTypeFamilies', // API 名称
      version: '2014-05-26', // API版本号
      protocol: 'HTTPS', // 请求协议：HTTPS或HTTP，建议使用HTTPS。
      method: 'POST', // 请求方法
      authType: 'AK', // 认证类型，默认即可。当OpenAPI支持匿名请求时，您可以传入 Anonymous 发起匿名请求。
      pathname: `/`, // API资源路径，RPC接口默认"/"，ROA接口从OpenAPI元数据中data.path获取资源路径。
      reqBodyType: 'json', // 接口请求体内容格式
      bodyType: 'json', // 接口响应体内容格式
});

配置请求参数

通过OpenApi.OpenApiRequest配置请求参数，请求参数支持通过query、body或stream传参，如何选择传参方式可根据元数据中的介绍选择，例如DescribeInstanceTypeFamilies的请求参数RegionId在元数据中信息为{"name":"RegionId","in":"query",...}}，其中"in":"query"表示RegionId通过query传递。

传参方式	描述
query	请求参数显示`"in":"query"`时，通过query传递参数。
body	请求参数显示`"in":"body"`或`"in": "formData"`时，通过body传递参数。在使用请求体（body）传递参数时，需要根据请求体的类型设置`reqBodyType`的值。
stream	在需要上传文件的场景，可通过stream传递文件流。

Node.js

// 场景一：设置查询参数（query）
let query = { 'RegionId': 'cn-hangzhou' };
let request = new OpenApi.OpenApiRequest({
    query: OpenApiUtil.default.query(query),
});

// 场景二：设置body参数，reqBodyType的值为json
// let body = {
//     'param1': 'value1',
//     'param2': 'value2',
// };
// let request = new OpenApi.OpenApiRequest({
//     body: OpenApiUtil.default.query(body),
// });

// 场景三：使用stream参数传递文件流
// let request = new OpenApi.OpenApiRequest({
//     stream: '<FILE_STREAM>', // <FILE_STREAM>需替换为实际的文件流
// });

// 场景四：设置body参数，reqBodyType的值为formData
// let formParams = {
//     'param1': 'value1',
//     'param2': 'value2',
// };
// let request = new OpenApi.OpenApiRequest({
//     body: formParams,
// });

Typescript

// 场景一：设置查询参数（query）
let query: { [key: string]: any } = { "RegionId": "cn-hangzhou" };
let request = new $OpenApi.OpenApiRequest({
    query: OpenApiUtil.query(query), 
});

// 场景二：设置body参数，reqBodyType的值为json
// let body = {
//    "param1": "value1",
//    "param2": "value2",
// };
// let request = new $OpenApi.OpenApiRequest({
//    body: OpenApiUtil.query(body),
// });

// 场景三：使用stream参数传递文件流
// let request = new $OpenApi.OpenApiRequest({
//    stream: '<FILE_STREAM>', // <FILE_STREAM>需替换为实际的文件流
// });

// 场景四：设置body参数，reqBodyType的值为formData
// let formParams = {
//    "param1": "value1",
//    "param2": "value2",
// };
// let request = new $OpenApi.OpenApiRequest({
//    body: formParams, // 直接传递表单参数
// });

发起请求

通过OpenApiClient调用callApi发起请求。同时，在请求过程中支持设置运行时参数，例如超时配置、代理配置等，更多信息请查看进阶配置。

Node.js

// 运行时参数
let runtime = new Util.RuntimeOptions({
    // true 忽略证书校验；false 设置证书校验
    // ignoreSSL: true,
    // 设置http代理
    // httpProxy: "http://xx.xx.xx.xx:xxxx",
    // httpsProxy: "https://username:password@xxx.xxx.xxx.xxx:9999",
    // 设置非代理地址
    // noProxy: '127.0.0.1,localhost',
    // 设置链接超时时间
    // connectTimeout: 10000,
    // 设置读取超时时间
    // readTimeout: 10000   
});
// 发起请求
let response = await client.callApi(params, request, runtime);
// 返回值为Map类型，可从Map中获得三类数据：body、headers、statusCode（HTTP返回的状态码 ）。
console.log(JSON.stringify(response.body))

Typescript

// 设置运行时参数
let runtime = new $Util.RuntimeOptions({
    // true 忽略证书校验；false 设置证书校验
    // ignoreSSL: true,
    // 设置http代理
    // httpProxy: "http://xx.xx.xx.xx:xxxx",
    // httpsProxy: "https://username:password@xxx.xxx.xxx.xxx:9999",
    // 设置非代理地址
    // noProxy: '127.0.0.1,localhost',
    // 设置链接超时时间
    // connectTimeout: 10000,
    // 设置读取超时时间
    // readTimeout: 10000   
});
// 发起请求
let response = await client.callApi(params, request, runtime);
// 返回值为 Map 类型，可从 Map 中获得三类数据：响应体 body、响应头 headers、HTTP 返回的状态码 statusCode。
console.log(JSON.stringify(response.body));

代码示例

示例：调用RPC风格的API

以调用ECS的DescribeInstanceTypeFamilies接口为例，展示如何使用泛化调用方式。

Node.js示例

const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const OpenApiUtil = require('@alicloud/openapi-util');

class Client {
    static async main() {
        // 从环境变量中获取阿里云访问密钥ID和密钥Secret。
        let config = new OpenApi.Config({
            accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
            accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
        });
        config.endpoint = `ecs-cn-hangzhou.aliyuncs.com`;
        let client = new OpenApi.default(config);
        let params = new OpenApi.Params({
            style: 'RPC', // API风格
            action: 'DescribeInstanceTypeFamilies', // API 名称
            version: '2014-05-26', // API版本号
            protocol: 'HTTPS', // API协议
            method: 'POST', // 请求方法
            authType: 'AK', // 认证类型，默认即可。当OpenAPI支持匿名请求时，您可以传入 Anonymous 发起匿名请求。
            pathname: `/`, // API资源路径，RPC接口默认"/"，ROA接口从OpenAPI元数据中data.path获取资源路径。
            reqBodyType: 'json', // 接口请求体内容格式
            bodyType: 'json', // 接口响应体内容格式
        });
        let query = { 'RegionId': 'cn-hangzhou' };
        let request = new OpenApi.OpenApiRequest({
            query: OpenApiUtil.default.query(query),
        });
        let runtime = new Util.RuntimeOptions({});
        let response = await client.callApi(params, request, runtime);
         console.log(JSON.stringify(response.body, null, 2))
    }
}

exports.Client = Client;
Client.main();

TypeScript示例

import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
import OpenApiUtil from '@alicloud/openapi-util';

export default class Client {
  static async main(): Promise<void> {
    // 从环境变量中获取阿里云访问密钥ID和密钥Secret。
    let config = new $OpenApi.Config({
      accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
      accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
    });
    config.endpoint = `ecs-cn-hangzhou.aliyuncs.com`;
    let client = new OpenApi(config);
    let params = new $OpenApi.Params({
      style: 'RPC', // API风格
      action: 'DescribeInstanceTypeFamilies', // API 名称
      version: '2014-05-26', // API版本号
      protocol: 'HTTPS', // API协议
      method: 'POST', // 请求方法
      authType: 'AK',
      pathname: `/`, // 接口 PATH
      reqBodyType: 'json', // 接口请求体内容格式
      bodyType: 'json', // 接口响应体内容格式
    });
    // 设置查询参数。
    let query: { [key: string]: any } = { "RegionId": "cn-hangzhou" };
    // 创建API请求对象。
    let request = new $OpenApi.OpenApiRequest({
       query: OpenApiUtil.query(query),
    });

    // 设置运行时参数
    let runtime = new $Util.RuntimeOptions({});
    // 返回值为 Map 类型，可从 Map 中获得三类数据：响应体 body、响应头 headers、HTTP 返回的状态码 statusCode。
    let response = await client.callApi(params, request, runtime);
    console.log(JSON.stringify(response.body));
  }
}

Client.main();

示例：调用RESTful（ROA）风格的API

以调用容器服务查询集群列表信息为例，展示如何使用泛化调用。

Node.js示例

const OpenApi = require('@alicloud/openapi-client');
const OpenApiUtil = require('@alicloud/openapi-util');
const Util = require('@alicloud/tea-util');
const Tea = require('@alicloud/tea-typescript');

class Client {
    static async main() {
        // 从环境变量中获取阿里云访问密钥ID和密钥Secret。
        let config = new OpenApi.Config({
            accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
            accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
        });
        config.endpoint = `cs.cn-qingdao.aliyuncs.com`;
        let client = new OpenApi.default(config);
        let params = new OpenApi.Params({
            // 接口名称
            action: 'DescribeClustersV1',
            // 接口版本
            version: '2015-12-15',
            // 接口协议
            protocol: 'HTTPS',
            // 接口 HTTP 方法
            method: 'GET',
            // 认证类型，默认即可。当OpenAPI支持匿名请求时，您可以传入 Anonymous 发起匿名请求。
            authType: 'AK',
            style: 'ROA',
            // API资源路径，RPC接口默认"/"，ROA接口从OpenAPI元数据中data.path获取资源路径。
            pathname: `/api/v1/clusters`,
            // 接口请求体内容格式
            reqBodyType: 'json',
            // 接口响应体内容格式
            bodyType: 'json',
        });
        // query params
        let queries = {};
        queries['name'] = 'cluster-demo';
        let request = new OpenApi.OpenApiRequest({
            query: OpenApiUtil.default.query(queries),
        });
        // runtime options
        let runtime = new Util.RuntimeOptions({});
        // 返回值为 Map 类型，可从 Map 中获得三类数据：响应体 body、响应头 headers、HTTP 返回的状态码 statusCode。
        let response = await client.callApi(params, request, runtime);
        console.log(response.body);
    }
}

exports.Client = Client;
Client.main();

TypeScript示例

import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import OpenApiUtil from '@alicloud/openapi-util';
import Util, * as $Util from '@alicloud/tea-util';
import * as $tea from '@alicloud/tea-typescript';

export default class Client {
  static async main(): Promise<void> {
    let config = new $OpenApi.Config({
      accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
      accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
    });
    config.endpoint = `cs.cn-qingdao.aliyuncs.com`;
    let client = new OpenApi(config);
    let params = new $OpenApi.Params({
      // 接口名称
      action: "DescribeClustersV1",
      // 接口版本
      version: "2015-12-15",
      // 接口协议
      protocol: "HTTPS",
      // 接口 HTTP 方法
      method: "GET",
      authType: "AK",
      style: "ROA",
      // 接口 PATH
      pathname: `/api/v1/clusters`,
      // 接口请求体内容格式
      reqBodyType: "json",
      // 接口响应体内容格式
      bodyType: "json",
    });
    // query params
    let queries: { [key: string]: any } = { "name": "cluster-demo" };
    let request = new $OpenApi.OpenApiRequest({
      query: OpenApiUtil.query(queries),
    });
    // runtime options
    let runtime = new $Util.RuntimeOptions({});
    // 返回值为 Map 类型，可从 Map 中获得三类数据：响应体 body、响应头 headers、HTTP 返回的状态码 statusCode。
    let response = await client.callApi(params, request, runtime);
    console.log(JSON.stringify(response.body));
  }
}

Client.main();