Node.js V2.0 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",
    // 設定非Proxy 位址
    // 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",
    // 設定非Proxy 位址
    // 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

以調用Container Service查詢叢集列表資訊為例，展示如何使用泛化調用。

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();