# @volcengine/imagex-openapi

[English](./README.md)

## 文档

火山引擎视频云API文档请点击[这里](https://www.volcengine.com/docs)

SDK的API文档请点击[这里](/docs/VodOverview.md)

火山引擎 AK&SK的文档请点击[这里](https://www.volcengine.com/docs/6291/65568)

## 版本变更

`@volcengine/imagex-openapi`对所有更改使用了[Semantic Versioning](https://semver.org)进行管理。 

### 所需Node版本

需要Nodejs版本 12或者更高

## 使用举例

### 设置AK&SK

有3种设置方式

#### 1. 在类初始化时通过选项进行设置

```javascript

import VolcSdk from '@volcengine/imagex-openapi';

const client = new VolcSdk({
  accessKey: 'your own accessKey',
  secretKey: 'your own secretKey'
});
```

#### 2. 使用环境变量进行设置

```bash
VOLC_ACCESSKEY="your ak" VOLC_SECRETKEY="your sk"
```

#### 3. 使用配置文件进行设置

在~/.volc/config文件中以json格式进行配置，格式如下:

```json
{"VOLC_ACCESSKEY":"your ak","VOLC_SECRETKEY":"your sk"}
```


### 设置Region、Host

你可以用如下方式为client设置Region、Host:

```javascript
import VCloudSdk from '@volcengine/imagex-openapi';

const client = new VCloudSdk({
  accessKey: 'your own accessKey',
  secretKey: 'your own secretKey',
  region: 'cn-north-1',
  host: 'open.volcengineapi.com'
});
```

### 日志记录和自定义日志

你可以通过设置logLevel或者通过设置LoggerOptions.log来定义你自己的日志策略，以此来记录SDK的请求

```javascript
import VCloudSdk from '@volcengine/imagex-openapi';
import winston from 'winston';

const appLogger = winston.createLogger();

const client = new VCloudSdk({
  accessKey: 'your own accessKey',
  secretKey: 'your own secretKey',
  loggerOptions: {
    level: 'debug',
    log: function(opts) {
      appLogger.log(opts);
    },
  },
});
```

### 重试和退避

对于失败的请求，你可以设置重试策略和退避策略

```javascript
import VCloudSdk from '@volcengine/imagex-openapi';

const client = new VCloudSdk({
  accessKey: 'your own accessKey',
  secretKey: 'your own secretKey',
  retryOptions: {
    policy: 'simple',
    retryLimit: 'both',
    maxPeriod: 10,
    maxAttempts: 30000,
  },
});
```

### 使用自定义的Http请求方法

SDK默认使用axios，一个promise-based的HTTP客户端来发起请求。如果需要，你也可以定义你自己的请求方法。

```javascript
import VCloudSdk from '@volcengine/imagex-openapi';
import customHttpRequest from './customHttpRequest';

const client = new VCloudSdk({
  accessKey: 'your own accessKey',
  secretKey: 'your own secretKey',
  region: 'cn-north-1',
  host: 'open.volcengineapi.com',
  httpRequest: customHttpRequest,
});
```

写一个自定的请求方法

```javascript
async function request(url, options) {
  const { headers = {}, proxy, maxBodyLength = 0 } = options;
  const reqOption: AxiosRequestConfig = {
    url,
    ...options,
    headers: {
      ...headers,
      'User-Agent': 'your own user agent'
    }
  };
  try {
    const res = await axios(reqOption);
    return {status: res.status, body: res.data, headers: res.headers};
  } catch(e) {
    // report metrics and so on...
  }
}
```

你可以在SDK中使用自定义的HTTP客户端，来模拟火山引擎的接口返回，以此来快速实现单元测试和集成测试，而不用同火山引擎建立链接。

### 插件机制

如果当前功能无法满足你的需求，你可以尝试自己开发插件。插件以以下格式编写

```javascript
function plugin () {
  return async (context, next) => {
    // ...
    // 在请求发送之前执行
    await next() // 执行后续插件,并发送请求
    // 在请求之后执行
    // ...
  }
}
```

以下是一个简单的插件例子

```javascript
export default function accessPlugin() {
    return async (context, next) => {
        if(checkAccess()) {
          await next();
        } else {
          context.response = 'has no access';
        }
        return;
    };
}
```

然后你需要在你的client里面注册这个插件

```javascript
const client = new VCloudSdk({
  accessKey: 'your own accessKey',
  secretKey: 'your own secretKey',
  region: 'cn-north-1',
  host: 'open.volcengineapi.com',
  httpRequest: customHttpRequest,
});
client.addPlugin(accessPlugin);
```

## 代理设置

你可以设置proxy选项来配置请求代理
#### 1. 在类初始化时设置代理

```javascript
import VCloudSdk from '@volcengine/imagex-openapi';

const client = new VCloudSdk({
  accessKey: 'your own accessKey',
  secretKey: 'your own secretKey', 
  proxy: {
      protocol: 'https',
      host: 'your own proxy host ip',
      auth: 'your own proxy host auth',
      port: 8080, // your own proxy host port
  }
});
```

#### 2.使用环境变量设置代理

`VOLC_PROXY_HOST="your own proxy host" VOLC_PROXY_PORT="your own proxy host port" `



## 获取帮助

如果你在安装或使用SDK的时候需要帮助，请先访问[火山引擎帮助中心](https://www.volcengine.com/product/contact)。

如果你发现了bug或者希望添加新的功能，请在此仓库下的issues下发起议题或者发起pull requests。

## 贡献

请参考 [Contributing](CONTRIBUTING.md)。

## Code of Conduct

请参考 [Code of Conduct](CODE_OF_CONDUCT.md)。

## Security

如果您在这个项目中发现了一个潜在的安全问题，或认为您可以  
如发现安全问题，请您通过我们的[安全中心](https://security.bytedance.com/src)或[漏洞报告电子邮件](sec@bytedance.com)通知字节跳动安全。 

Please do **not** create a public GitHub issue.

## License
此项目使用 [Apache-2.0 License](LICENSE)。