文档帮助平台
首页服务端API参考 Yealink APIs 使用Yealink APIs
使用Yealink APIs
更新时间：2024-11-08 06:27:06

使用Yealink APIs

Yealink APIs允许开发者访问和操作Yealink云视讯下的资源，包括但不限于：查询用户详情、编辑用户和添加会议等操作。本章将叙述如何正确的调用Yealink API。

Yealink API

  • Version： 1.0.0
  • Host： api.ylyun.com/v2
  • Protocols： HTTPS
  • Accepts： application/json
  • Responds With： application/json

身份认证

对Yealink API发出的每个HTTP请求都必须经过身份认证。此操作是为了保证访问服务的客户端是否为系统已登记的用户。在身份认证的过程中，使用OAuth2.0协议。

在调用API之前，您需要从亿联会议平台中获得Client ID 与 Client Secret，用于申请访问 token。一个企业只能申请一组Client ID 与Client Secret。

Client授权方式只适用于服务器之间的身份认证。如果在开放客户端使用（如：移动APP），就存在安全风险，Client Secret和访问令牌可能会被盗用。

流程说明

用户申请访问 token 和发起请求的流程如下：

client_credentials_flow

  1. 第三方应用服务器向Yealink API服务器发起申请访问 token 请求并且携带Client ID和Client Secret
  2. Yealink API服务器验证Client ID和Client Secret信息是否正确
  3. 验证成功后返回访问 token
  4. 第三方应用服务器发起业务请求，并且携带访问 token
  5. Yealink API服务器验证是否存在访问令牌，然后验证访问令牌的有效性。
  6. 转发请求给Yealink业务服务器
  7. Yealink业务服务器将处理后的结果返回给Yealink API服务器
  8. Yealink API服务器将响应结果透传给第三方应用服务器

如果访问 token 失效，还需要提供相应的代码重新向服务器获取 token。

申请访问token

请求方法

POST

请求地址

/token

请求参数

参数 参数类型 数据类型 是否必需 描述
Authorization Header String 是 Basic base64Encode(client_id:client_secret)，以冒号连接Client ID和Client Secret，然后进行Base64编码
timestamp Header String 是 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
nonce Header String 是 随机数，最大长度32位
grant_type Body String 是 client_credentials

HTTP状态码

返回值 描述
200 操作成功，详见响应参数
400 客户端传参异常，详见异常响应参数
401 鉴权失败，详见异常响应参数
500 服务端异常，详见异常响应参数

响应参数

参数 数据类型 描述
access_token String 访问令牌
token_type String bearer
expires_in Long 访问令牌有效时间，单位为秒

异常响应参数

参数 数据类型 描述
error String 根据OAuth2协议定义提供。表示一个错误代码字符串，可以用于对错误进行分类，并对错误进行处理
code String 服务端定义的错误码，用于快速定位问题
requestId String 服务端生成的请求ID，用于在服务端跟踪请求执行情况。能够帮助开发人员快速定位问题
message String 简单明了的错误描述，能够被终端用户所理解

请求消息示例

POST /v2/token HTTP/1.1
Content-Type: application/json
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
    "grant_type": "client_credentials"
}

响应参数示例

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "[JWT TOKEN]",
  "token_type": "bearer",
  "expires_in": 86400
}

异常响应参数

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error": "invalid_request",
  "code": "70011",
  "requestId": "255d1aef",
  "message": "The provided value for the input parameter 'grant_type' is not valid."
}

发起业务请求

所有的 API 请求都必须通过 HTTPS 发出。请求的基础 URL 是https://api.ylyun.com/v2/。完整的 URL 根据操作的资源不同而定。

每次请求 API 时，均需提供 3 个 HTTP Request Header，具体如下：

名称 数据类型 描述
Authorization String 鉴权信息。格式为：Bearer [ACCESS TOKEN]
timestamp String 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
nonce String 随机数，最大长度32位

HTTP请求头部示例

Authorization: Bearer [ACCESS TOKEN]
timestamp: 1568693976264
nonce: 097e0ac619ba41f68f16f1955787feb9
本页目录