文档中心





视频通话 (Legacy)

Console 官网社区技术支持





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

分类: 集成类平台: All Platforms 最后更新时间: 2023/02/05 20:30:09

功能描述

在使用 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@agora.io 获取水晶球内嵌的客户 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());
    }
}

Golang

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

node.js

// 基于 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

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

Golang

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
}

node.js

// 基于 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());
    }
}

Golang

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

node.js

// 基于 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"))

这篇文章对你有帮助吗？

是

否