Agora REST Client for Go

English | 简体中文

agora-rest-client-go is an open-source project written in Go, specifically designed for the Agora REST API. It includes wrappers and internal implementations of the official Agora REST API interfaces, making it easier for developers to integrate the server-side Agora REST API.

Important

This SDK has undergone some testing to ensure its basic functionality works correctly. However, due to the complexity of software development, we cannot guarantee it is completely free of defects. We encourage community developers and users to actively participate and help improve this project.

Features

• Encapsulates the request and response handling of the Agora REST API, simplifying the communication process with the Agora REST API.
• Provides automatic switching to the best domain in case of DNS resolution failure, network errors, or request timeouts, ensuring the availability of the REST API service.
• Offers easy-to-use APIs to easily implement common functions of the Agora REST API, such as starting and stopping cloud recording.
• Based on Go language, it is efficient, concurrent, and scalable.

Supported Services

• Cloud Recording
• Cloud Transcoder
• Conversational AI Engine

Environment Setup

• Go 1.18 or later
• App ID and App Certificate obtained from the Agora Console
• Basic Auth credentials from the Agora Console
• Enable the relevant service capabilities on the Agora Console

Installation

Install the dependency from GitHub using the following command:

go get -u github.com/AgoraIO-Community/agora-rest-client-go

Usage Example

Here is an example of calling the cloud recording service:

package main

import (
	"context"
	"log"
	"time"

	"github.com/AgoraIO-Community/agora-rest-client-go/agora"
	"github.com/AgoraIO-Community/agora-rest-client-go/agora/auth"
	"github.com/AgoraIO-Community/agora-rest-client-go/agora/domain"
	agoraLogger "github.com/AgoraIO-Community/agora-rest-client-go/agora/log"
	"github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording"
	cloudRecordingAPI "github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording/api"
	"github.com/AgoraIO-Community/agora-rest-client-go/services/cloudrecording/scenario/mixrecording"
)

const (
	appId    = "<your appId>"
	cname    = "<your cname>"
	uid      = "<your uid>"
	username = "<the username of basic auth credential>"
	password = "<the password of basic auth credential>"
	token    = "<your token>"
)

var storageConfig = &cloudRecordingAPI.StorageConfig{
	Vendor:    0,
	Region:    0,
	Bucket:    "",
	AccessKey: "",
	SecretKey: "",
	FileNamePrefix: []string{
		"recordings",
	},
}

func main() {
	// Initialize Agora Config
	config := &agora.Config{
		AppID:      appId,
		Credential: auth.NewBasicAuthCredential(username, password),
		// Specify the region where the server is located. Options include CN, EU, AP, US.
		// The client will automatically switch to use the best domain based on the configured region.
		DomainArea: domain.CN,
		// Specify the log output level. Options include DebugLevel, InfoLevel, WarningLevel, ErrLevel.
		// To disable log output, set logger to DiscardLogger.
		Logger: agoraLogger.NewDefaultLogger(agoraLogger.DebugLevel),
	}

	// Initialize the cloud recording service client
	cloudRecordingClient, err := cloudrecording.NewClient(config)
	if err != nil {
		log.Fatal(err)
	}

	// Call the Acquire API of the cloud recording service client
	acquireResp, err := cloudRecordingClient.MixRecording().
		Acquire(context.TODO(), cname, uid, &mixrecording.AcquireMixRecodingClientRequest{})
	// Handle non-business errors
	if err != nil {
		log.Fatal(err)
	}

	// Handle business response
	if acquireResp.IsSuccess() {
		log.Printf("acquire success:%+v\n", acquireResp)
	} else {
		log.Fatalf("acquire failed:%+v\n", acquireResp)
	}

	// Call the Start API of the cloud recording service client
	resourceId := acquireResp.SuccessRes.ResourceId
	startResp, err := cloudRecordingClient.MixRecording().
		Start(context.TODO(), resourceId, cname, uid, &mixrecording.StartMixRecordingClientRequest{
			Token: token,
			RecordingConfig: &cloudRecordingAPI.RecordingConfig{
				ChannelType:  1,
				StreamTypes:  2,
				MaxIdleTime:  30,
				AudioProfile: 2,
				TranscodingConfig: &cloudRecordingAPI.TranscodingConfig{
					Width:            640,
					Height:           640,
					FPS:              15,
					BitRate:          800,
					MixedVideoLayout: 0,
					BackgroundColor:  "#000000",
				},
				SubscribeAudioUIDs: []string{
					"#allstream#",
				},
				SubscribeVideoUIDs: []string{
					"#allstream#",
				},
			},
			RecordingFileConfig: &cloudRecordingAPI.RecordingFileConfig{
				AvFileType: []string{
					"hls",
					"mp4",
				},
			},
			StorageConfig: storageConfig,
		})
	// Handle non-business errors
	if err != nil {
		log.Fatal(err)
	}

	// Handle business response
	if startResp.IsSuccess() {
		log.Printf("start success:%+v\n", startResp)
	} else {
		log.Fatalf("start failed:%+v\n", startResp)
	}

	sid := startResp.SuccessResponse.Sid
	// Query
	for i := 0; i < 6; i++ {
		queryResp, err := cloudRecordingClient.MixRecording().
			QueryHLSAndMP4(context.TODO(), resourceId, sid)
		// Handle non-business errors
		if err != nil {
			log.Fatal(err)
		}

		// Handle business response
		if queryResp.IsSuccess() {
			log.Printf("query success:%+v\n", queryResp)
		} else {
			log.Printf("query failed:%+v\n", queryResp)
		}
		time.Sleep(time.Second * 10)
	}

	// Call the Stop API of the cloud recording service client
	stopResp, err := cloudRecordingClient.MixRecording().
		Stop(context.TODO(), resourceId, sid, cname, uid, true)
	// Handle non-business errors
	if err != nil {
		log.Fatal(err)
	}

	// Handle business response
	if stopResp.IsSuccess() {
		log.Printf("stop success:%+v\n", stopResp)
	} else {
		log.Printf("stop failed:%+v\n", stopResp)
	}
}

For more examples, see Example.

Contribution

This project welcomes and accepts contributions. If you encounter any issues or have suggestions for improvements, please open an issue or submit a Pull Request.

SemVer Versioning

This project uses Semantic Versioning (SemVer) to manage versions. The format is MAJOR.MINOR.PATCH.

• MAJOR version indicates incompatible changes.
• MINOR version indicates backward-compatible new features or enhancements.
• PATCH version indicates backward-compatible bug fixes and maintenance. For more details, please refer to the Semantic Versioning specification.

References

• Agora API Documentation

License

This project is licensed under the MIT License. For more details, please refer to the LICENSE file.