文档平台 API 中心 云通信 服务端集成指引

服务端集成指引

最近更新时间:2018-06-06 14:30:23

内容提要

服务端集成 是 App 后台通过云通讯提供的一系列 REST API 来管理自身 App 的数据。云通信提供的 REST API 参见 REST API接口列表
本文档将介绍如何通过 REST API 来进行数据管理,您将了解到:

  1. 调用 REST API 需要哪些前提条件;
  2. 如何调试 REST API,包括:
    2.1 通过云通讯 REST API 调试工具来调用 REST API;
    2.2 通过 Postman 来调试 REST API;
    2.3 通过 PHP Server SDK 中的工具来调试 REST API;
  3. 如何在服务端调用 REST API,包括:
    3.1 在 PHP 中集成 PHP Server SDK。

REST API

REST API 是腾讯云暴露给 App 后台的 HTTP 管理接口,其主要目的在于为 App 后台提供一个后台管理入口。更多介绍参见 REST API简介

前提条件

要调用 REST API,您必须首先

  1. 在云通信中创建 App,具体方法参见 应用接入指引
  2. 为您的 App 指定管理员帐号,具体方法参见 设置App管理员帐号

特别提醒:调用 REST API 时请务必使用 App 管理员帐号,否则会导致不必要的调用错误。

调用方法

REST API 的请求 URL、请求方式、包体格式参见 REST API简介。目前支持的 REST API 参见 REST API接口列表

本文档将介绍如下几种方式来调用 REST API,分别是:

  1. 使用云通讯 REST API 调试工具;
  2. 使用 Postman;
  3. 使用 PHP Server SDK 中的 REST API 调试工具。

在“调用示例”一节中,将通过具体的案例来演示调用 REST API 的各种方法。

调用示例

本文档将通过一个完整的示例来展示 REST API 的各种调用方法。该示例包含以下步骤:

  1. 导入帐号到云通信(使用云通讯 REST API 调试工具);
  2. 为导入的设置帐号的基本资料(使用 Postman);
  3. 创建一个群组,包含初始群成员(使用 PHP Server SDK 中的工具)。

准备工作:获取 App 管理员帐号的签名

确保 App 管理员帐号存在。打开 App 控制台,单击【应用配置】:

进入页面之后,查看【帐号体系集成】,确保后续过程均使用 App 管理员帐号(此处假定 App 管理员帐号的为 myadmin):

为 App 管理员帐号生成 usersig:

  1. Linux 下生成 usersig 的方式参见:linux 下生成 sig 和校验 sig
  2. Windows 下生成 usersig 的方式参见:windows 下生成 sig 和校验 sig

例如,在 Windows 下,生成命令是:

.\tls_licence_tools.exe gen .\keys\private_key sig 3600 1400000478 myadmin

生成 usersig 之后,便完成了调用 REST API 所需的准备工作。

导入帐号到云通信(使用云通讯 REST API 调试工具)

下面将使用 云通讯 REST API 调试工具 来导入一个帐号,用户名为 lilei。
(需要导入该帐号的原因是:在后续内容中我们为 lilei 设置资料,并以其为群主来创建一个群,但目前该帐号尚不存在。因此我们需要把 lilei 这个帐号导入到云通讯中。)

打开 云通讯 REST API 调试工具,填写调用参数如下:

单击【提交】,可以看到应答包体如下:

至此,便完成 lilei 这个帐号的导入。

为导入的设置帐号的基本资料(使用 Postman)

本节我们将使用 Postman 来调用设置用户资料的接口(v4/profile/portrait_set)为上一节导入的帐号设置基本资料,具体工作是:将用户 lilei 的昵称设置为“李雷”。

安装 Postman

注:安装 Postman 需要能够访问 google 应用商店,如果您的网络无法访问 google 相关网站,建议您使用云通讯 REST API 调试工具。

Postman 是一款功能强大的网页调试与发送网页 HTTP 请求的 Chrome 插件。其安装方法是:打开 Chrome 浏览器,在 Chrome 网上应用商店中搜索 Postman,并【添加至Chrome】,如下图所示:
安装完毕后,Postman 将出现在 Chrome 的应用中,如下图所示:

设置用户的基本资料
打开 Postman,依照如下指引填写参数:

  1. 选择请求方式为 POST;
  2. 在地址栏中填写请求 URL:https://console.tim.qq.com/v4/profile/portrait_set
  3. 单击地址栏右侧的“Params”按钮,在下方的参数列表中填写各项请求参数,各参数的含义参见 REST API 参数说明。
  4. 单击 Body;
  5. 单击 raw,目的是填写文本请求包(JSON 格式);
  6. 填写请求包。

如下图所示:

完成所有请求参数的填写之后,单击右上角的“Send”按钮发起请求,将会收到如下应答(注意将红框处选择 JSON):

至此,我们便实现了通过 Postman 调用 REST API 来设置用户资料。

创建一个群组,包含初始群成员(使用 PHP Server SDK 中的工具)

本节我们将使用 PHP Server SDK 来调用创建群组的接口(v4/group_open_http_svc/create_group),具体工作是:创建一名字为 “MyFirstGrouplilei” 的群,群主设置为 “lilei”。
PHP Server SDK 是云通讯 PHP 后台服务提供的 REST API 集成 SDK,该 SDK 将一些常用的 REST API 封装成了 PHP 函数。PHP Server SDK 的下载与集成方法参见:PHP Server SDK
完成 PHP Server SDK 的下载与部署后,需要修改 TimRestApiConfig.json 中的 REST API 请求参数:

其中 private_pem_path 为 App 私钥文件的路径。
调用如下命令创建群:

php TimRestApiGear.php group_open_http_svc create_group Public MyFirstGroup lilei

输出如下:

至此,我们便通过创建了一个群,我们可以在 App 控制台的“群组管理”页中看到该群:

在后台服务中调用 REST API

在后台服务中调用 REST API,本质上是发起 HTTPS POST 请求。云通信提供了 Server SDK 来封装对 REST API 的调用,开发者可以将其直接集成到您的服务端代码中。

  1. PHP Server SDK
  2. Node.js Server SDK
  3. Java Server SDK(敬请期待);
  4. Golang Server SDK(敬请期待)。

如果有其他疑问,您也可以在问答社区中寻求帮助。前往问答社区 >