如何在 RESTful API 中进行 HTTP 基本认证和 Token 认证?

功能描述

在使用 RESTful API 前，你需要通过 HTTP 基本认证或 Token 认证。

HTTP 基本认证

使用声网提供的客户 ID 和客户密钥生成一个使用 Base64 算法编码的凭证，并在 HTTP 请求头部的 Authorization 字段中填入该凭证。以下产品的 RESTful API 需要 HTTP 基本认证：

Token 认证

AccessToken2

警告

AccessToken2 自 2022 年 8 月 18 日正式上线，如需使用 AccessToken2，务必传入新的请求头重新进行服务端鉴权。

你需要在 HTTP 请求中 header 的 Authorization: agora token= 字段填入服务端生成的 RTM Token。以下产品和服务的 RESTful API 需要 Token 认证：

AccessToken

你需要在 HTTP 请求中 header 的 x-agora-token 字段和 x-agora-uid 字段分别填入：

服务端生成的 RTM Token。
生成 RTM Token 时使用的 RTM 用户 ID。

注意

一般情况下，声网建议你在服务端进行 HTTP 基本认证和 Token 认证，否则会有数据泄露的风险。

实现 HTTP 基本认证

实现方法

参考以下步骤获取客户 ID 和客户密钥：

在声网控制台点击右上角账户名，在下拉菜单中点击 RESTful API，进入 RESTful API 页面。
在 RESTful API 页面，点击添加密钥按钮，就会生成一组客户 ID 和客户密钥。然后点击提交按钮，完成客户 ID 和客户密钥的创建。
在对应的客户密钥栏点击下载按钮。仔细阅读弹窗提示后，点击下载。请妥善保管下载的 key_and_secret.txt 文件，其中包含你的客户 ID 和客户密钥。
在请求认证的代码中，填入客户 ID (key) 和客户密钥 (secret)，生成一个使用 Base64 算法编码的凭证，并在 HTTP 请求头部的 Authorization 字段中填入该凭证。

注意

客户 ID 和客户密钥仅用于访问 RESTful API。客户密钥只能下载一次，下载后将不在控制台保存，请妥善保管。

当使用水晶球内嵌功能时，你需要联系 sales@shengwang.cn 获取水晶球内嵌的客户 ID 与客户密钥进行 HTTP 基本认证。

示例代码

下列示例代码实现了 HTTP 基本认证并使用服务端 RESTful API 发送一个简单的请求，获取所有的声网项目信息：

Java
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;


// 基于 Java 实现的 HTTP 基本认证示例，使用 RTC 的服务端 RESTful API
public class Base64Encoding {

    public static void main(String[] args) throws IOException, InterruptedException {

        // 客户 ID
        final String customerKey = "Your customer key";
        // 客户密钥
        final String customerSecret = "Your customer secret";

        // 拼接客户 ID 和客户密钥并使用 base64 编码
        String plainCredentials = customerKey + ":" + customerSecret;
        String base64Credentials = new String(Base64.getEncoder().encode(plainCredentials.getBytes()));
        // 创建 authorization header
        String authorizationHeader = "Basic " + base64Credentials;

        HttpClient client = HttpClient.newHttpClient();

        // 创建 HTTP 请求对象
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.agora.io/dev/v1/projects"))
                .GET()
                .header("Authorization", authorizationHeader)
                .header("Content-Type", "application/json")
                .build();
        // 发送 HTTP 请求
        HttpResponse<String> response = client.send(request,
                HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

Go
package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
"encoding/base64"
)

// 基于 Golang 实现的 HTTP 基本认证示例，使用 RTC 的服务端 RESTful API
func main() {

// 客户 ID
customerKey := "Your customer key"
// 客户密钥
customerSecret := "Your customer secret"

// 拼接客户 ID 和客户密钥并使用 base64 进行编码
plainCredentials := customerKey + ":" + customerSecret
base64Credentials := base64.StdEncoding.EncodeToString([]byte(plainCredentials))

url := "https://api.agora.io/dev/v1/projects"
method := "GET"

payload := strings.NewReader(``)

client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)

if err != nil {
    fmt.Println(err)
    return
}
// 增加 Authorization header
req.Header.Add("Authorization", "Basic " + base64Credentials)
req.Header.Add("Content-Type", "application/json")

// 发送 HTTP 请求
res, err := client.Do(req)
if err != nil {
    fmt.Println(err)
    return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(string(body))
}

PHP
<?php
// 基于 PHP 实现的 HTTP 基本认证示例，使用 RTC 的服务端 RESTful API
// 客户 ID
$customerKey = "Your customer key";
// 客户密钥
$customerSecret = "Your customer secret";
// 拼接客户 ID 和客户密钥
$credentials = $customerKey . ":" . $customerSecret;

// 使用 base64 进行编码
$base64Credentials = base64_encode($credentials);
// 创建 authorization header
$arr_header = "Authorization: Basic " . $base64Credentials;

$curl = curl_init();
// 发送 HTTP 请求
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.agora.io/dev/v1/projects',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',

CURLOPT_HTTPHEADER => array(
    $arr_header,
    'Content-Type: application/json'
),
));

$response = curl_exec($curl);

if($response === false) {
    echo "Error in cURL : " . curl_error($curl);
}

curl_close($curl);

echo $response;

C#
using System;
using System.IO;
using System.Net;
using System.Text;

// 基于 C# 实现的 HTTP 基本认证示例，使用 RTC 的服务端 RESTful API
namespace Examples.System.Net
{
    public class WebRequestPostExample
    {
        public static void Main()
        {
            // 客户 ID
            string customerKey = "Your customer key";
            // 客户密钥
            string customerSecret = "Your customer secret";
            // 拼接客户 ID 和客户密钥
            string plainCredential = customerKey + ":" + customerSecret;

            // 使用 base64 进行编码
            var plainTextBytes = Encoding.UTF8.GetBytes(plainCredential);
            string encodedCredential = Convert.ToBase64String(plainTextBytes);
            // 创建 authorization header
            string authorizationHeader = "Authorization: Basic " + encodedCredential;

            // 创建请求对象
            WebRequest request = WebRequest.Create("https://api.agora.io/dev/v1/projects");
            request.Method = "GET";

            // 添加 authorization header
            request.Headers.Add(authorizationHeader);
            request.ContentType = "application/json";

            WebResponse response = request.GetResponse();
            Console.WriteLine(((HttpWebResponse)response).StatusDescription);

            using (Stream dataStream = response.GetResponseStream())
            {
                StreamReader reader = new StreamReader(dataStream);
                string responseFromServer = reader.ReadToEnd();
                Console.WriteLine(responseFromServer);
            }

            response.Close();
        }
    }
}

JavaScript
// 基于 node.js 实现的 HTTP 基本认证示例，使用 RTC 的服务端 RESTful API
const https = require('https')
// 客户 ID
const customerKey = "Your customer key"
// 客户密钥
const customerSecret = "Your customer secret"
// 拼接客户 ID 和客户密钥
const plainCredential = customerKey + ":" + customerSecret
// 使用 base64 进行编码
encodedCredential = Buffer.from(plainCredential).toString('base64')
authorizationField = "Basic " + encodedCredential


// 设置请求参数
const options = {
hostname: 'api.agora.io',
port: 443,
path: '/dev/v1/projects',
method: 'GET',
headers: {
    'Authorization':authorizationField,
    'Content-Type': 'application/json'
}
}

// 创建请求对象，发送请求
const req = https.request(options, res => {
console.log(`Status code: ${res.statusCode}`)

res.on('data', d => {
    process.stdout.write(d)
})
})

req.on('error', error => {
console.error(error)
})

req.end()

Python
# -- coding utf-8 --
# Python 3
# 基于 Python 实现的 HTTP 基本认证示例，使用 RTC 的服务端 RESTful API
import base64
import http.client


# 客户 ID
customer_key = "Your customer key"
# 客户密钥
customer_secret = "Your customer secret"

# 拼接客户 ID 和客户密钥
credentials = customer_key + ":" + customer_secret
# 使用 base64 进行编码
base64_credentials = base64.b64encode(credentials.encode("utf8"))
credential = base64_credentials.decode("utf8")

# 通过基本 URL 创建连接对象
conn = http.client.HTTPSConnection("api.agora.io")

payload = ""

# 创建 Header 对象
headers = {}
# 添加 Authorization 字段
headers['Authorization'] = 'basic ' + credential

headers['Content-Type'] = 'application/json'

# 发送请求
conn.request("GET", "/dev/v1/projects", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

实现 Token 认证

AccessToken2 实现方法

警告

AccessToken2 自 2022 年 8 月 18 日正式上线，如需使用 AccessToken2，务必传入新的请求头重新进行服务端鉴权。

下列示例代码实现了 Token 认证并使用 RTM RESTful API 发送一个简单的请求，获取用户事件：

Java
Golang
node.js
Python

Java
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;


// 基于 Java 实现的 HTTP 基本认证示例，使用 RTC 的服务端 RESTful API
class TokenAuthExample {
    public static void main(String[] args) throws IOException, InterruptedException {
        // 请输入你生成的 RTM Token
        final String tokenValue = "input your token value here";
        // 请输入你的 AppID
        final String appID = "input your app ID here";

        String urlStr = String.format("https://api.agora.io/dev/v2/project/%s/rtm/vendor/user_events", appID);
        String authValue = String.format("agora token=%s", tokenValue);

        // 创建 HTTP 请求对象
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(urlStr))
                .GET()
                .header("Authorization", authValue)
                .header("Content-Type", "application/json")
                .build();

        // 发送 HTTP 请求
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request,
                HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

Go
package main

import (
        "fmt"
        "io/ioutil"
        "net/http"
)

func main() {
        if err := tokenAuthExamle(); err != nil {
                panic(err)
        }
}

// 基于 Golang 实现的 HTTP Token 认证示例，使用 RTC 的服务端 RESTful API
func tokenAuthExamle() error {
        var (
                // 输入你生成的 Token
                tokenValue = "input the token value here"
                // 输入你的 AppID
                appID     = "input your app ID here"
                urlstr    = fmt.Sprintf("https://api.agora.io/dev/v2/project/%s/rtm/vendor/user_events", appID)
                authValue = fmt.Sprintf("agora token=%s", tokenValue)
        )

        // 构造 HTTP 请求
        req, err := http.NewRequest(http.MethodGet, urlstr, nil)
        if err != nil {
                return fmt.Errorf("failed to new http request, %w", err)
        }
        // 设置 Authorization header
        req.Header.Set("Authorization", authValue)
        req.Header.Set("Content-Type", "application/json")

        // 发送 HTTP 请求
        resp, err := http.DefaultClient.Do(req)
        if err != nil {
                return fmt.Errorf("failed to send request, %w", err)
        }
        defer resp.Body.Close()

        // 读取响应体
        body, err := ioutil.ReadAll(resp.Body)
        if err != nil {
                return fmt.Errorf("failed to read response body, %w", err)
        }

        // 判定 StatusCode
        if resp.StatusCode/100 != 2 {
                return fmt.Errorf("StatusCode(%d) != 2xx, %s", resp.StatusCode, string(body))
        }

        // 打印出正常返回的响应体
        fmt.Println(string(body))
        return nil
}

JavaScript
// 基于 node.js 实现的 Token 认证示例，使用 RTM 的用户事件 RESTful API
const https = require('https')


// 请输入你生成的 RTM Token
var token_value = "input your token here"
// 请输入你的 AppID
var app_id = "input your app ID"

var url_path = `/dev/v2/project/${app_id}/rtm/vendor/user_events`
var auth_token = `agora token=${token_value}`

// 设置请求参数
const options = {
hostname: 'api.agora.io',
port: 443,
path: url_path,
method: 'GET',
headers: {
    // 在 header 中添加 Authorization 字段
    'Authorization': auth_token,
    'Content-Type': 'application/json'
}
}

const req = https.request(options, res => {
console.log(`Status code: ${res.statusCode}`)
res.on('data', d => {
    process.stdout.write(d)
})
})

req.on('error', error => {
console.error(error)
})

req.end()

Python
import http.client
# 基于 Python 实现的 Token 认证示例，使用 RTM 的用户事件 RESTful API

# 请输入你生成的 Token
token_value = "input your token here"
# 请输入你的 AppID
app_id = "input your app ID here"


url_path = "/dev/v2/project/{0}/rtm/vendor/user_events".format(app_id)
auth_value = "agora token={0}".format(token_value)

# 通过基本 URL 创建连接对象
conn = http.client.HTTPSConnection("api.agora.io")
# 创建 header
headers = {}
# 添加鉴权 header
headers['Authorization'] = auth_value
headers['Content-Type'] = 'application/json'
payload = ""
# 发送请求
conn.request("GET", url_path, payload, headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

AccessToken 实现方法

下列示例代码实现了 Token 认证并使用 RTM RESTful API 发送一个简单的请求，获取用户事件：

Java
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;


// 基于 Java 实现的 Token 认证示例，使用 RTM 的用户事件 RESTful API
public class Base64Encoding {

    public static void main(String[] args) throws IOException, InterruptedException {

        // RTM Token
        String tokenHeader = "Your RTM token";
        // 生成 RTM Token 时使用的 user ID
        String uidHeader = "test_user";

        HttpClient client = HttpClient.newHttpClient();


        // 构建请求对象
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events"))
                .GET()
                // 在 header 中添加 x-agora-token 字段
                .header("x-agora-token", tokenHeader )
                // 在 header 中添加 x-agora-uid 字段
                .header("x-agora-uid", uidHeader)
                .header("Content-Type", "application/json")
                .build();
        // 发送请求
        HttpResponse<String> response = client.send(request,
                HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

Go
package main


import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

// 基于 Golang 实现的 Token 认证示例，使用 RTM 的用户事件 RESTful API
func main() {

// RTM Token
tokenHeader := "Your RTM Token"
// 生成 RTM Token 时使用的 user ID
uidHeader := "test_user"


url := "https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events"
method := "GET"

payload := strings.NewReader(``)

client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)

if err != nil {
    fmt.Println(err)
    return
}
// 在 header 中添加 x-agora-token 字段
req.Header.Add("x-agora-token", tokenHeader)
// 在 header 中添加 x-agora-uid 字段
req.Header.Add("x-agora-uid", uidHeader)
req.Header.Add("Content-Type", "application/json")

// 发送请求
res, err := client.Do(req)
if err != nil {
    fmt.Println(err)
    return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(string(body))
}

PHP
<?php
// 基于 PHP 实现的 Token 认证示例，使用 RTM 的用户事件 RESTful API


// RTM Token
$token = "Your RTM Token";
// 生成 RTM Token 时使用的 user ID
$uid = "test_user";
// 在 header 中添加 x-agora-token 字段
$token_header = "x-agora-token: " . $token;
// 在 header 中添加 x-agora-uid 字段
$uid_header = "x-agora-uid: " . $uid;

$curl = curl_init();
// 发送请求
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',

CURLOPT_HTTPHEADER => array(
    $token_header,
    $uid_header,
    'Content-Type: application/json'
),
));

$response = curl_exec($curl);

if($response === false) {
    echo "Error in cURL : " . curl_error($curl);
}

curl_close($curl);

echo $response;

C#
using System;
using System.IO;
using System.Net;
using System.Text;
// 基于 C# 实现的 Token 认证示例，使用 RTM 的用户事件 RESTful API
namespace Examples.System.Net
{
    public class WebRequestPostExample
    {
        public static void Main()
        {

            // RTM Token
            string token = "Your RTM Token";
            // 生成 RTM Token 时使用的 user ID
            string uid = "userA";
            // 在 header 中添加 x-agora-token 字段
            string tokenHeader = "x-agora-token: " + token;
            // 在 header 中添加 x-agora-uid 字段
            string uidHeader = "x-agora-uid: " + uid;

            WebRequest request = WebRequest.Create("https://api.agora.io/dev/v2/project/<Your App ID>/rtm/vendor/user_events");
            request.Method = "GET";

            // 在请求中添加 header
            request.Headers.Add(tokenHeader);
            request.Headers.Add(uidHeader);

            request.ContentType = "application/json";

            // 获取响应
            WebResponse response = request.GetResponse();
            Console.WriteLine(((HttpWebResponse)response).StatusDescription);


            using (Stream dataStream = response.GetResponseStream())
            {
                StreamReader reader = new StreamReader(dataStream);
                string responseFromServer = reader.ReadToEnd();
                Console.WriteLine(responseFromServer);
            }

            response.Close();
        }
    }
}

JavaScript
// 基于 node.js 实现的 Token 认证示例，使用 RTM 的用户事件 RESTful API
const https = require('https')


// RTM Token
token = "Your RTM Token"
// 生成 RTM Token 时使用的 user ID
uid = "test_user"

// 设置请求参数
const options = {
hostname: 'api.agora.io',
port: 443,
path: '/dev/v2/project/<Your App ID>/rtm/vendor/user_events',
method: 'GET',
headers: {
    // 在 header 中添加 x-agora-token 字段
    'x-agora-token':token,
    // 在 header 中添加 x-agora-uid 字段
    'x-agora-uid': uid,
    'Content-Type': 'application/json'
}
}

const req = https.request(options, res => {
console.log(`Status code: ${res.statusCode}`)
res.on('data', d => {
    process.stdout.write(d)
})
})

req.on('error', error => {
console.error(error)
})

req.end()

Python
import http.client
# 基于 Python 实现的 Token 认证示例，使用 RTM 的用户事件 RESTful API

# 通过基本 URL 创建连接对象
conn = http.client.HTTPSConnection("api.agora.io")
# 创建 header
headers = {}
# 为 header 添加 x-agora-token 字段，内容为 RTM Token
headers['x-agora-token'] = "Your RTM Token"
# 为 header 添加 x-agora-uid 字段，内容为生成 RTM Token 时使用的 user ID
headers['x-agora-uid'] = "test_user"
headers['Content-Type'] = 'application/json'
payload = ""
# 发送请求
conn.request("GET", "/dev/v2/project/<Your App ID>/rtm/vendor/user_events", payload, headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

功能描述​

HTTP 基本认证​

Token 认证​

AccessToken2​

AccessToken​

实现 HTTP 基本认证​

实现方法​

示例代码​

实现 Token 认证​

AccessToken2 实现方法​

AccessToken 实现方法​