diff --git a/media-gateway/reference/rest-api/endpoints/flow-configuration-template/create-reset-template.mdx b/media-gateway/reference/rest-api/endpoints/flow-configuration-template/create-reset-template.mdx index 01c7ded79..74908f5d5 100644 --- a/media-gateway/reference/rest-api/endpoints/flow-configuration-template/create-reset-template.mdx +++ b/media-gateway/reference/rest-api/endpoints/flow-configuration-template/create-reset-template.mdx @@ -9,6 +9,4 @@ description: > import CreateTemplate from '@docs/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/create-reset-template.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/flow-configuration-template/delete-template.mdx b/media-gateway/reference/rest-api/endpoints/flow-configuration-template/delete-template.mdx index cd497a4ec..be6e713fd 100644 --- a/media-gateway/reference/rest-api/endpoints/flow-configuration-template/delete-template.mdx +++ b/media-gateway/reference/rest-api/endpoints/flow-configuration-template/delete-template.mdx @@ -9,6 +9,4 @@ description: > import DeleteTemplate from '@docs/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/delete-template.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/flow-configuration-template/set-global-template.mdx b/media-gateway/reference/rest-api/endpoints/flow-configuration-template/set-global-template.mdx index 80bf95d1a..eb1210a63 100644 --- a/media-gateway/reference/rest-api/endpoints/flow-configuration-template/set-global-template.mdx +++ b/media-gateway/reference/rest-api/endpoints/flow-configuration-template/set-global-template.mdx @@ -9,6 +9,4 @@ description: > import SetGlobalTemplate from '@docs/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/set-global-template.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/flow-configuration-template/update-template.mdx b/media-gateway/reference/rest-api/endpoints/flow-configuration-template/update-template.mdx index 3babfc0d3..96733223c 100644 --- a/media-gateway/reference/rest-api/endpoints/flow-configuration-template/update-template.mdx +++ b/media-gateway/reference/rest-api/endpoints/flow-configuration-template/update-template.mdx @@ -9,6 +9,4 @@ description: > import UpdateTemplate from '@docs/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/update-template.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/message-notification-service/query-ip-address.mdx b/media-gateway/reference/rest-api/endpoints/message-notification-service/query-ip-address.mdx index 6f169a4e0..355e40c15 100644 --- a/media-gateway/reference/rest-api/endpoints/message-notification-service/query-ip-address.mdx +++ b/media-gateway/reference/rest-api/endpoints/message-notification-service/query-ip-address.mdx @@ -9,6 +9,4 @@ description: > import QueryIpAddress from '@docs/shared/media-gateway/reference/rest-api/endpoints/message-notification-service/query-ip-address.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/streaming-information/force-disconnection.mdx b/media-gateway/reference/rest-api/endpoints/streaming-information/force-disconnection.mdx index 4d2765048..297cd9f7b 100644 --- a/media-gateway/reference/rest-api/endpoints/streaming-information/force-disconnection.mdx +++ b/media-gateway/reference/rest-api/endpoints/streaming-information/force-disconnection.mdx @@ -9,6 +9,4 @@ description: > import ForceDisconnect from '@docs/shared/media-gateway/reference/rest-api/endpoints/streaming-information/force-disconnection.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/streaming-information/mute.mdx b/media-gateway/reference/rest-api/endpoints/streaming-information/mute.mdx index 579d15692..81365759d 100644 --- a/media-gateway/reference/rest-api/endpoints/streaming-information/mute.mdx +++ b/media-gateway/reference/rest-api/endpoints/streaming-information/mute.mdx @@ -9,6 +9,4 @@ description: > import Mute from '@docs/shared/media-gateway/reference/rest-api/endpoints/streaming-information/mute.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-information.mdx b/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-information.mdx index 2e1fa8bd2..c0f9c452f 100644 --- a/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-information.mdx +++ b/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-information.mdx @@ -9,6 +9,4 @@ description: > import QueryStreamingInfo from '@docs/shared/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-information.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-list.mdx b/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-list.mdx index 2bcdb9d0c..92bfb5589 100644 --- a/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-list.mdx +++ b/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-list.mdx @@ -9,6 +9,4 @@ description: > import QueryStreamingList from '@docs/shared/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-list.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/streaming-key/create-streaming-key.mdx b/media-gateway/reference/rest-api/endpoints/streaming-key/create-streaming-key.mdx index d7a54840a..4b5492f2c 100644 --- a/media-gateway/reference/rest-api/endpoints/streaming-key/create-streaming-key.mdx +++ b/media-gateway/reference/rest-api/endpoints/streaming-key/create-streaming-key.mdx @@ -9,6 +9,4 @@ description: > import CreateStreamingKey from '@docs/shared/media-gateway/reference/rest-api/endpoints/streaming-key/create-streaming-key.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/streaming-key/delete-streaming-key.mdx b/media-gateway/reference/rest-api/endpoints/streaming-key/delete-streaming-key.mdx index d8468f651..932bf432d 100644 --- a/media-gateway/reference/rest-api/endpoints/streaming-key/delete-streaming-key.mdx +++ b/media-gateway/reference/rest-api/endpoints/streaming-key/delete-streaming-key.mdx @@ -9,6 +9,4 @@ description: > import DeleteStreamingKey from '@docs/shared/media-gateway/reference/rest-api/endpoints/streaming-key/delete-streaming-key.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/media-gateway/reference/rest-api/endpoints/streaming-key/query-streaming-key-information.mdx b/media-gateway/reference/rest-api/endpoints/streaming-key/query-streaming-key-information.mdx index 842a476bb..72672af3a 100644 --- a/media-gateway/reference/rest-api/endpoints/streaming-key/query-streaming-key-information.mdx +++ b/media-gateway/reference/rest-api/endpoints/streaming-key/query-streaming-key-information.mdx @@ -9,6 +9,4 @@ description: > import QueryStreamingKeyInfo from '@docs/shared/media-gateway/reference/rest-api/endpoints/streaming-key/query-streaming-key-information.mdx'; -export const toc = [{}]; - - \ No newline at end of file + diff --git a/shared/media-gateway/reference/rest-api/authorization.mdx b/shared/media-gateway/reference/rest-api/authorization.mdx index da6f3947b..7065abf37 100644 --- a/shared/media-gateway/reference/rest-api/authorization.mdx +++ b/shared/media-gateway/reference/rest-api/authorization.mdx @@ -1,13 +1,11 @@ -- HTTP Basic Authentication - Every time you send an HTTP request, you must pass in a credential in the `Authorization` field in the HTTP request header. See [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication) on how to generate it. +- HTTP Basic Authentication + Basic authentication is a simple authentication scheme built into the HTTP protocol. To use it, send your HTTP requests with an `Authorization` header that contains the word Basic followed by a space and a base64-encoded string `username:password`. Example: `Authorization: Basic ZGVtbzpwQDU1dzByZA==` - HTTP HMAC Authentication - Every time you send an HTTP request, you must pass in an API key in the `Authorization` field in the HTTP request header. See [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-hmac-http-authentication) on how to generate it. - Example: `Authorization: 123` diff --git a/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/create-reset-template.mdx b/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/create-reset-template.mdx index 33ae0c365..eb8c2f05f 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/create-reset-template.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/create-reset-template.mdx @@ -1,118 +1,324 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -This method creates or resets a flow configuration template. + -### Prototype + -- Method: `PUT` -- Endpoint: `https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/stream-templates/:templateId` +This method creates or resets a flow configuration template. For more information, see [Flow configuration templates](#flow-configuration-templates). -In the template, you can configure transcoding parameters for video or audio streams, as well as parameters for mitigating network latency. +To use flow configuration templates with other APIs, see [Use flow templates with other APIs.](#use-flow-templates-with-other-apis). -Up to 10 flow configuration templates can be created under an app ID, each with a unique `templatedId`. Specify the `templateId` when creating a template; if a template corresponding to this ID already exists, the existing template will be reset with the incoming body data. +By default, a template is not set for the app ID. That is, video transcoding is not enabled. -There are two ways to use flow configuration templates, which can be used in combination: +### Request -- Specify a global template for the app ID: All streaming keys under the app ID will use this template by default. -- Specify a configuration template for a specific streaming key: When using this key to push streams, the specific template will be used. +**Path parameters** -By default, a template is not set for the app ID. That is, video transcoding is not enabled. + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • `na`: North America
    • +
  • `eu`: Europe
    • +
  • `ap`: Asia, except mainland China
    • +
  • `cn`: Mainland China
    • +
+ + Make sure that: +
    +
  • The `region` value is the same as for the input source stream.
    • +
  • The domain names for setting the `region` parameter and streaming are the same.
    • +
  • The `region` value is in lowercase.
    • +
+ + + + The flow configuration template ID. The value can only include the following characters: a-z, A-Z, 0-9, and the length cannot exceed 12 bytes. The value of the flow configuration template ID can be set according to your business use-case. For example, `"720p"` and `"1080p"` for different target resolutions, or `"gameA"` and `"gameB"`for different game use-cases. + -### Request parameters +**Headers** -**Authentication** + + + The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. + + + + + - +**Request body** -**Path parameters** +The request body consists of a JSON Object type `settings` and includes the following fields: -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `region` | String | Required | Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
| -| `templateId` | String | Required | The flow configuration template ID. The value can only include the following characters: a-z, A-Z, 0-9, and the length cannot exceed 12 bytes. The value of the flow configuration template ID can be set according to your business use-case. For example, `"720p"` and `"1080p"` for different target resolutions, or `"gameA"` and `"gameB"`for different game use-cases.| + + + Audio and video transcoding parameter configuration. + + Video transcoding parameters. + + Whether to enable video transcoding. Disabled by default. + + + The transcoding mode. +
    +
  • force (default): Force transcoding.
    • +
  • adaptive: Adaptive transcoding.
    • +
+ + + The codec format for transcoding. Supported values: H.264 (default) and VP8. + + + The width in the encoding resolution (0 to 1920). If 0, follows source stream width. + + + The height in the encoding resolution (0 to 1920). If 0, follows source stream height. + + + The video encoding frame rate (0 to 60). If 0, follows source stream frame rate. + + + Video stream configuration for low-quality stream. + + The width of the video stream (0 to 1920). Must be less than video.width. Defaults to video.width / 2. + + + The height of the video stream (0 to 1920). Must be less than video.height. Defaults to video.height / 2. + + + The frame rate of the video stream (0 to 60). Must be ≤ video.fps. Defaults to 15. + + + The bitrate of the low-quality video stream (in Kbps). Must be less than video.bitrate. Defaults automatically. + + + + Video encoding bitrate in Kbps. If simulcastStream is enabled, must be greater than simulcastStream.bitrate. Defaults automatically. For more information, see [video profiles](#video-profiles). + + + + Audio transcoding parameters. + + Whether to enable audio transcoding. Enabled by default. + + + Encoded audio profile. Default is 0 (48 KHz, music encoding, mono, max 64 Kbps). Contact support for other profiles. + + + Encoding bitrate in Kbps (64-320). Defaults based on profile. + + + + + Network jitter buffer (effective only when video transcoding is enabled). + + Maximum length in ms. Default: 500 ms (adds delay to reduce lag caused by network jitter). + + + Maximum length in ms. Default: 1000 ms. Must be greater than jitterBuffer.size. If exceeded, acceleration is enabled. + + + + +### Response **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + -**Request body** +**Response body** -The request body consists of a JSON Object type `settings` and includes the following fields: +If the status code is `200`, the request succeeds, and the response body includes the following parameters: -| Parameter | Data type | Required/Optional | Description | -| :------------ | :-------- |:----------------- | :---------------------- | -| `transcoding` | Object | Optional | Audio and video transcoding parameter configuration.
  • `video`: Object, video transcoding parameters. Includes the following fields:
    • `enabled`: Whether to enable video transcoding. Disabled by default.
    • `mode`: String, the transcoding mode.
      • `force`(default): Force transcoding.
      • `adaptive`: Adaptive transcoding:
        • When the source stream has B-frames, transcoding is enabled.
        • When B-frames appear in the first 2 seconds of streaming, transcoding is enabled.
        • When B-frames appear during streaming, transcoding is enabled once they appear. During this transition, the audience will see that the host stops and then immediately resumes streaming.
    • `codec`: String, the codec format for transcoding. Supported values are `H.264` (default) and `VP8`.
    • `width`: Number, the width in the encoding resolution. The value range is 0 to 1920. If left blank or filled in with `0`, it will follow the width of the source stream.
    • `height` Number, the height in the encoding resolution. The value range is 0 to 1920. If left blank or filled in with `0`, it will follow the height of the source stream.The `width` and `height` parameters must be filled at the same time, or both left blank.
    • `fps`: Number, the video encoding frame rate in fps. The value range is 0 to 60. If left blank or filled in with `0`, it will follow the frame rate of the source stream.
    • `simulcastStream`: Object, video stream configuration. If provided, enable the low-quality stream and specify the transcoding parameters for it.
      • `width`: Number, the width of the video stream in px. The value range is 0 to 1920. The value of this parameter must be less than `video.width`. If left blank or filled in with `0`, it will use the value of `video.width`/2.
      • `height` Number, the height of the video stream. The value range is 0 to 1920. The value of this parameter must be less than `video.height`. If left blank or filled in with `0`, it will use the value of `video.height`/2.
      • `fps`: Number, the frame rate of the video stream in fps. The value range is 0 to 60. The value of this parameter must be less than or equal to `video.fps`. If left blank or filled in with `0`, it will use `15` as default value.
      • `bitrate`: The bitrate of the low-quality video stream, in Kbps. The value of this parameter must be less than `video.bitrate`. If left blank or filled in with `0`, an appropriate bitrate will be set automatically based on the `video.bitrate`, resolution and `fps` of the low-quality stream.
    • `bitrate`: Video encoding bitrate in Kbps.
      • If the low-quality stream is enabled (`simulcastStream` is provided), then this field is required and the value must be greater than `simulcastStream.bitrate`.
      • If the low-quality video stream is not enabled, this field is optional. If not filled in, an appropriate bitrate will be set automatically based on the `width`, `height`, and `fps` values. See the following table:
        Resolution (width × height, px)Frame rate (fps)Bitrate (Kbps)
        640 × 36015680
        640 × 360301030
        848 × 48015920
        848 × 480301400
        960 × 540151100
        960 × 540301670
        1280 × 720151600
        1280 × 720302400
        1920 × 1080152500
        1920 × 1080303780
        1920 × 1080605730
        When the low-quality stream is not enabled, it is recommended to use the automatically set bitrate.
  • `audio`: Object, audio transcoding parameters. Includes the following fields:
    • `enabled`: Boolean, whether to enable audio transcoding. Enabled by default.
    • `profile`: Number, encoded audio use-cases. The default value is `0`, which means 48 KHz sampling rate, music encoding, mono, and the maximum encoding rate is 64 Kbps. If you want to set other settings profile, please [contact technical support](mailto:support@agora.io).
    • `bitrate`: Number, the encoding bitrate in Kbps. If left blank, it is determined by the `profile` value. The range is 64 to 320.
| -| `jitterBuffer`| Object | Optional | Network jitter buffer. Only takes effect when video transcoding is enabled.
  • `size`: Number, the maximum length in ms. The default value is 500, which means that will add 500 ms to the end-to-end delay to reduce lag caused by network jitter.
  • `maxSize`: Number, the maximum length in ms. The default value is 1000. Make sure that the value of this field is greater than `jitterBuffer.size`. When `jitterBuffer` exceeds this value, will enable acceleration until it returns to `jitterBuffer.size`.
| - - -### Request example - -```shell -curl --location -g --request PUT 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/stream-templates/{{templateId}}' \ ---data '{ - "settings": { - "transcoding": { - "video": { - "enabled": true, - "codec": "H.264", - "width": 1280, - "height": 720, - "fps": 24, - "bitrate": 2200, - "simulcastStream": { - "width": 960, - "height": 540, - "fps": 24, - "bitrate": 1670 - } - }, - "audio": { - "enabled": false, - "profile": 3 - } - }, - "jitterBuffer": { - "size": 500, - "maxSize": 800 - } - } -}' -``` + + + The status of this request. success means the request succeeds. + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). -### Response parameters + -**Headers** +## Reference -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| +This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product. -**Response body** +### Flow configuration templates -For details about possible response status codes, see [Response status codes](../../response-status-codes). +In the template, you can configure transcoding parameters for video or audio streams, as well as parameters for mitigating network latency. -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. +Up to 10 flow configuration templates can be created under an app ID, each with a unique `templatedId`. Specify the `templateId` when creating a template; if a template corresponding to this ID already exists, the existing template will be reset with the incoming body data. -If the status code is `200`, the request succeeds, and the response body includes the following parameters: +### Use flow templates with other APIs -| Parameter | Type | Description | -| :--------------- | :----- | :----------------------------------------------------------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | +There are two ways to use flow configuration templates, which can be used in combination: -### Response example +- Specify a global template for the app ID: All streaming keys under the app ID will use this template by default. +- Specify a configuration template for a specific streaming key: When using this key to push streams, the specific template will be used. -The following is a response example for a successful request: +### Video profiles + +
Resolution (width × height, px)Frame rate (fps)Bitrate (Kbps)
640 × 36015680
640 × 360301030
848 × 48015920
848 × 480301400
960 × 540151100
960 × 540301670
1280 × 720151600
1280 × 720302400
1920 × 1080152500
1920 × 1080303780
1920 × 1080605730
+ + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + ```shell + curl --location -g --request PUT 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/stream-templates/{{templateId}}' \ + --data '{ + "settings": { + "transcoding": { + "video": { + "enabled": true, + "codec": "H.264", + "width": 1280, + "height": 720, + "fps": 24, + "bitrate": 2200, + "simulcastStream": { + "width": 960, + "height": 540, + "fps": 24, + "bitrate": 1670 + } + }, + "audio": { + "enabled": false, + "profile": 3 + } + }, + "jitterBuffer": { + "size": 500, + "maxSize": 800 + } + } + }' + ``` + + + ```js + const url = `https://api.agora.io/${region}/v1/projects/${appId}/rtls/ingress/stream-templates/${templateId}`; + + const data = { + settings: { + transcoding: { + video: { + enabled: true, + codec: "H.264", + width: 1280, + height: 720, + fps: 24, + bitrate: 2200, + simulcastStream: { + width: 960, + height: 540, + fps: 24, + bitrate: 1670 + } + }, + audio: { + enabled: false, + profile: 3 + } + }, + jitterBuffer: { + size: 500, + maxSize: 800 + } + } + }; + + fetch(url, { + method: "PUT", + headers: { + "Content-Type": "application/json", + "Accept": "application/json", + "Authorization": "Basic " + }, + body: JSON.stringify(data) + }) + .then(response => response.json()) + .then(data => console.log(data)) + .catch(error => console.error("Error:", error)); + ``` + + + ```python + url = f"https://api.agora.io/{region}/v1/projects/{appId}/rtls/ingress/stream-templates/{templateId}" + + headers = { + "Content-Type": "application/json", + "Accept": "application/json", + "Authorization": "Basic " + } + + data = { + "settings": { + "transcoding": { + "video": { + "enabled": True, + "codec": "H.264", + "width": 1280, + "height": 720, + "fps": 24, + "bitrate": 2200, + "simulcastStream": { + "width": 960, + "height": 540, + "fps": 24, + "bitrate": 1670 + } + }, + "audio": { + "enabled": False, + "profile": 3 + } + }, + "jitterBuffer": { + "size": 500, + "maxSize": 800 + } + } + } + + response = requests.put(url, headers=headers, data=json.dumps(data)) + ``` + + + +
+
```json { "status": "success" } ``` - - \ No newline at end of file +
+ + diff --git a/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/delete-template.mdx b/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/delete-template.mdx index 0f8513bfb..fc7a1479c 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/delete-template.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/delete-template.mdx @@ -1,70 +1,128 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -This method deletes a flow configuration template. + -### Prototype + -- Method: `DELETE` -- Endpoint: `https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/stream-templates/:templateId` +This method deletes a flow configuration template.
  • After deletion, the stream currently being pushed using the template will not be affected and will still be pushed according to the template parameters. Deletion will take effect from the next push, including normal push and disconnection/reconnection).
  • If the template associated with the streaming key is deleted, the global template under the app ID will be used by default. If no global template is configured, streaming will be performed according to the no-template setting, that is, video transcoding will not be enabled.
 -### Request parameters - -**Authentication** - - +### Request **Path parameters** -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `region` | String | Required | Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
| -| `templateId` | String | Required | The flow configuration template ID. The value can only include the following characters: a-z, A-Z, 0-9, and the length cannot exceed 12 bytes. The value of the flow configuration template ID can be set according to your business use-case. For example, `"720p"` and `"1080p"` for different target resolutions, or `"gameA"` and `"gameB"`for different game use-cases.| + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • na: North America
    • +
  • eu: Europe
    • +
  • ap: Asia, except mainland China
    • +
  • cn: Mainland China
    • +
+ + Make sure that: +
    +
  • The region value is the same as for the input source stream.
    • +
  • The domain names for setting the region parameter and streaming are the same.
    • +
  • The region value is in lowercase.
    • +
+ + + +The flow configuration template ID. The value can only include the following characters: a-z, A-Z, 0-9, and the length cannot exceed 12 bytes. The value of the flow configuration template ID can be set according to your business use-case. For example, `"720p"` and `"1080p"` for different target resolutions, or `"gameA"` and `"gameB"`for different game use-cases. + **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | - -### Request example - -```shell -curl --location -g --request DELETE 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/stream-templates/{{templateId}}' -``` + + + The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. + + + + + -### Response parameters +### Response **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + **Response body** -For details about possible response status codes, see [Response status codes](../../response-status-codes). - -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. - If the status code is `200`, the request succeeds, and the response body includes the following parameters: -| Parameter | Type | Description | -| :--------------- | :----- | :----------------------------------------------------------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | - -### Response example - -The following is a response example for a successful request: + + + The status of this request. success means the request succeeds. + + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). + + + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + ```shell + curl --location -g --request DELETE 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/stream-templates/{{templateId}}' + ``` + + + ```js + fetch(`https://api.agora.io/your-region/v1/projects/your-appId/rtls/ingress/stream-templates/your-templateId`, { + method: "DELETE", + headers: { "Accept": "application/json", "Authorization": "Basic " } + }) + .then(res => res.json()) + .then(console.log) + .catch(console.error); + ``` + + + ```python + url = "https://api.agora.io/your-region/v1/projects/your-appId/rtls/ingress/stream-templates/your-templateId" + headers = {"Accept": "application/json", "Authorization": "Basic "} + + res = requests.delete(url, headers=headers) + print(res.json() if res.status_code == 200 else res.text) + ``` + + +
+
```json { "status": "success" } ``` - - \ No newline at end of file +
+ + diff --git a/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/set-global-template.mdx b/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/set-global-template.mdx index 7f3d30ba6..e90422408 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/set-global-template.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/set-global-template.mdx @@ -1,83 +1,156 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -This method sets a global flow configuration template, that is, the template that applies to all streaming keys under the app ID. + -### Prototype + -- Method: `PUT` -- Endpoint: `https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/appconfig` +This method sets a global flow configuration template, that is, the template that applies to all streaming keys under the app ID. Before calling this API, [create a flow configuration template](create-reset-template). -### Request parameters - -**Authentication** - - +### Request **Path parameters** -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `region` | String | Required | Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
| + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • na: North America
    • +
  • eu: Europe
    • +
  • ap: Asia, except mainland China
    • +
  • cn: Mainland China
    • +
+ + Make sure that: +
    +
  • The region value is the same as for the input source stream.
    • +
  • The domain names for setting the region parameter and streaming are the same.
    • +
  • The region value is in lowercase.
    • +
+ + **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | + + + The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. + + + + + **Request body** The request body consists of a JSON Object type `settings` and includes the following fields: -| Parameter | Data type | Required/Optional | Description | -| :------------ | :-------- |:----------------- | :---------------------- | -| `defaultStreamTemplate` | String | Required | The flow configuration template ID. For users of the beta version: Previously this API could also be used to set the transcoding parameters. Now it is recommended that you use the [template creation API](create-reset-template) instead. If you have used this API to set `transcoding`, the current flow is the following:
  • If you reset `defaultStreamTemplate`, the `transcoding` previously set through this API will automatically become invalid, and the parameters in the new template will prevail.
  • If you do not reset `defaultStreamTemplate`, the `transcoding` previously set through this API will remain as the default global configuration for this app ID.
| - - -### Request example - -```shell -curl --location -g --request PUT 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/appconfig' \ ---data '{ - "settings": { - "defaultStreamTemplate": "720p" - } -}' -``` - -### Response parameters + + + The flow configuration template ID. + + For users of the beta version: Previously this API could also be used to set the transcoding parameters. Now it is recommended that you use the [template creation API](create-reset-template) instead. If you have used this API to set `transcoding`, the current flow is the following: +
    +
  • If you reset `defaultStreamTemplate`, the `transcoding` previously set through this API will automatically become invalid, and the parameters in the new template will prevail.
    • +
  • If you do not reset `defaultStreamTemplate`, the `transcoding` previously set through this API will remain as the default global configuration for this app ID.
    • +
+ + + + +### Responses **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + **Response body** -For details about possible response status codes, see [Response status codes](../../response-status-codes). - -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. - If the status code is `200`, the request succeeds, and the response body includes the following parameters: -| Parameter | Type | Description | -| :--------------- | :----- | :----------------------------------------------------------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | - -### Response example - -The following is a response example for a successful request: - -```json + + + The status of this request. success means the request succeeds. + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). + + + + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + ```shell + curl --location -g --request PUT 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/appconfig' \ + --data '{ + "settings": { + "defaultStreamTemplate": "720p" + } + }' + ``` + + + ```js + fetch(`https://api.agora.io/your-region/v1/projects/your-appId/rtls/ingress/appconfig`, { + method: "PUT", + headers: { + "Content-Type": "application/json", + "Accept": "application/json", + "Authorization": "Basic " + }, + body: JSON.stringify({ settings: { defaultStreamTemplate: "720p" } }) + }) + .then(res => res.json()) + .then(console.log) + .catch(console.error); + ``` + + + ```python + url = "https://api.agora.io/your-region/v1/projects/your-appId/rtls/ingress/appconfig" + headers = { + "Content-Type": "application/json", + "Accept": "application/json", + "Authorization": "Basic " + } + data = {"settings": {"defaultStreamTemplate": "720p"}} + + res = requests.put(url, headers=headers, json=data) + ``` + + + +
+
+```shell { "status": "success" } ``` - - \ No newline at end of file +
+ + diff --git a/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/update-template.mdx b/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/update-template.mdx index 076e16455..5ed4311ee 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/update-template.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/flow-configuration-template/update-template.mdx @@ -1,102 +1,297 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -This method updates a flow configuration template. + -### Prototype + -- Method: `PATCH` -- Endpoint: `https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/stream-templates/:templateId` +This method updates a flow configuration template.
  • This interface can only be called if the flow configuration template already exists.
  • Modifications to a flow configuration template will only take effect after the stream is re-pushed. Considering the synchronization delay between the gateway and the database, wait 3 minutes after calling this interface before re-pushing the stream.
 -### Request parameters - -**Authentication** - - +### Request **Path parameters** -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `region` | String | Required | Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
| -| `templateId` | String | Required | The flow configuration template ID. The value can only include the following characters: a-z, A-Z, 0-9, and the length cannot exceed 12 bytes. The value of the flow configuration template ID can be set according to your business use-case. For example, `"720p"` and `"1080p"` for different target resolutions, or `"gameA"` and `"gameB"`for different game use-cases.| + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • na: North America
    • +
  • eu: Europe
    • +
  • ap: Asia, except mainland China
    • +
  • cn: Mainland China
    • +
+ + Make sure that: +
    +
  • The region value is the same as for the input source stream.
    • +
  • The domain names for setting the region parameter and streaming are the same.
    • +
  • The region value is in lowercase.
    • +
+ + + + The flow configuration template ID. The value can only include the following characters: a-z, A-Z, 0-9, and the length cannot exceed 12 bytes. + + The value of the flow configuration template ID can be set according to your business use-case. For example: +
    +
  • "720p" and "1080p" for different target resolutions.
    • +
  • "gameA" and "gameB" for different game use cases.
    • +
+ **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | + + + The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. + + + + + **Request body** The request body consists of a JSON Object type `settings` and includes the following fields: -| Parameter | Data type | Required/Optional | Description | -| :------------ | :-------- |:----------------- | :---------------------- | -| `transcoding` | Object | Optional | Audio and video transcoding parameter configuration.
  • `video`: Object, video transcoding parameters. Includes the following fields:
    • `enabled`: Whether to enable video transcoding. Disabled by default.
    • `mode`: String, the transcoding mode:
      • `force`(default): Force transcoding.
      • `adaptive`: Adaptive transcoding.
        • When the source stream has B-frames, transcoding is enabled.
        • When B-frames appear in the first 2 seconds of streaming, transcoding is enabled.
        • When B-frames appear during streaming, transcoding is enabled once they appear. During this transition, the audience will see that the host stops and then immediately resumes streaming.
    • `codec`: String, the codec format for transcoding. Supported values are `H.264` (default) and `VP8`.
    • `width`: Number, the width in the encoding resolution. The value range is 0 to 1920. If left blank or filled in with `0`, it will follow the width of the source stream.
    • `height` Number, the height in the encoding resolution. The value range is 0 to 1920. If left blank or filled in with `0`, it will follow the height of the source stream.The `width` and `height` parameters must be filled at the same time, or both left blank.
    • `fps`: Number, the video encoding frame rate in fps. The value range is 0 to 60. If left blank or filled in with `0`, it will follow the frame rate of the source stream.
    • `simulcastStream`: Object, video stream configuration. If provided, enable the low-quality stream and specify the transcoding parameters for it.
      • `width`: Number, the width of the video stream in px. The value range is 0 to 1920. The value of this parameter must be less than `video.width`. If left blank or filled in with `0`, it will use the value of `video.width`/2.
      • `height` Number, the height of the video stream. The value range is 0 to 1920. The value of this parameter must be less than `video.height`. If left blank or filled in with `0`, it will use the value of `video.height`/2.
      • `fps`: Number, the frame rate of the video stream in fps. The value range is 0 to 60. The value of this parameter must be less than or equal to `video.fps`. If left blank or filled in with `0`, it will use `15` as default value.
      • `bitrate`: The bitrate of the low-quality video stream, in Kbps. The value of this parameter must be less than `video.bitrate`. If left blank or filled in with `0`, an appropriate bitrate will be set automatically based on the `video.bitrate`, resolution and `fps` of the low-quality stream.
    • `bitrate`: Video encoding bitrate in Kbps.
      • If the low-quality stream is enabled (`simulcastStream` is provided), then this field is required and the value must be greater than `simulcastStream.bitrate`.
      • If the low-quality video stream is not enabled, this field is optional. If not filled in, an appropriate bitrate will be set automatically based on the `width`, `height`, and `fps` values. See the following table:
        Resolution (width × height, px)Frame rate (fps)Bitrate (Kbps)
        640 × 36015680
        640 × 360301030
        848 × 48015920
        848 × 480301400
        960 × 540151100
        960 × 540301670
        1280 × 720151600
        1280 × 720302400
        1920 × 1080152500
        1920 × 1080303780
        1920 × 1080605730
        When the low-quality stream is not enabled, it is recommended to use the automatically set bitrate.
  • `audio`: Object, audio transcoding parameters. Includes the following fields:
    • `enabled`: Boolean, whether to enable audio transcoding. Enabled by default.
    • `profile`: Number, encoded audio use-cases. The default value is `0`, which means 48 KHz sampling rate, music encoding, mono, and the maximum encoding rate is 64 Kbps. If you want to set other settings profile, please [contact technical support](mailto:support@agora.io).
    • `bitrate`: Number, the encoding bitrate in Kbps. If left blank, it is determined by the `profile` value. The range is 64 to 320.
| -| `jitterBuffer`| Object | Optional | Network jitter buffer. Only takes effect when video transcoding is enabled.
  • `size`: Number, the maximum length in ms. The default value is 500, which means that will add 500 ms to the end-to-end delay to reduce lag caused by network jitter.
  • `maxSize`: Number, the maximum length in ms. The default value is 1000. Make sure that the value of this field is greater than `jitterBuffer.size`. When `jitterBuffer` exceeds this value, will enable acceleration until it returns to `jitterBuffer.size`.
| + + + Audio and video transcoding parameter configuration. + + Video transcoding parameters. + + Whether to enable video transcoding. Disabled by default. + + + The transcoding mode. +
    +
  • force (default): Force transcoding.
    • +
  • adaptive: Adaptive transcoding.
    • +
+ + + The codec format for transcoding. Supported values: H.264 (default) and VP8. + + + The width in the encoding resolution (0 to 1920). If 0, follows source stream width. + + + The height in the encoding resolution (0 to 1920). If 0, follows source stream height. + + + The video encoding frame rate (0 to 60). If 0, follows source stream frame rate. + + + Video stream configuration for low-quality stream. + + The width of the video stream (0 to 1920). Must be less than video.width. Defaults to video.width / 2. + + + The height of the video stream (0 to 1920). Must be less than video.height. Defaults to video.height / 2. + + + The frame rate of the video stream (0 to 60). Must be ≤ video.fps. Defaults to 15. + + + The bitrate of the low-quality video stream (in Kbps). Must be less than video.bitrate. Defaults automatically. + + + + Video encoding bitrate in Kbps. If simulcastStream is enabled, must be greater than simulcastStream.bitrate. Defaults automatically. For more information, see [video profiles](#video-profiles). + + + + Audio transcoding parameters. + + Whether to enable audio transcoding. Enabled by default. + + + Encoded audio profile. Default is 0 (48 KHz, music encoding, mono, max 64 Kbps). Contact support for other profiles. + + + Encoding bitrate in Kbps (64-320). Defaults based on profile. + + + + + Network jitter buffer (effective only when video transcoding is enabled). + + Maximum length in ms. Default: 500 ms (adds delay to reduce lag caused by network jitter). + + + Maximum length in ms. Default: 1000 ms. Must be greater than jitterBuffer.size. If exceeded, acceleration is enabled. + + +
  • To ensure a successful request, do not set the required fields to `null` or leave them empty.
  • The parameters supported for the update are the following: `transcoding.video`, `transcoding.audio`, and `jitterBuffer`. This means that, for example, if you only want to update the `fps` field of `transcoding.video`, you need to pass in the entire `transcoding.video` field with the modified `fps` field and other fields unchanged.
  • `transcoding.video`, `transcoding.audio`, and `jitterBuffer` are independent of each other. If only `transcoding.video` is passed in, then only its parameters will be updated and the parameters of `transcoding.audio` and `jitterBuffer` will not be affected.
 -### Request example -```shell -curl --location -g --request PUT 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/stream-templates/{{templateId}}' \ ---data ' -{ - "settings": { - "transcoding": { - "video": { - "enabled": true, - "codec": "H.264", - "width": 1280, - "height": 720, - "fps": 24, - "bitrate": 2200, - "simulcastStream": { - "width": 960, - "height": 540, +### Response + +**Headers** + + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + +**Response body** + +If the status code is `200`, the request succeeds, and the response body includes the following parameters: + + + + The status of this request. success means the request succeeds. + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). + + + + +## Reference + +This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product. + +### Video profiles + +
Resolution (width × height, px)Frame rate (fps)Bitrate (Kbps)
640 × 36015680
640 × 360301030
848 × 48015920
848 × 480301400
960 × 540151100
960 × 540301670
1280 × 720151600
1280 × 720302400
1920 × 1080152500
1920 × 1080303780
1920 × 1080605730
+ + + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + ```shell + curl --location -g --request PUT 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/stream-templates/{{templateId}}' \ + --data ' + { + "settings": { + "transcoding": { + "video": { + "enabled": true, + "codec": "H.264", + "width": 1280, + "height": 720, "fps": 24, - "bitrate": 1670 + "bitrate": 2200, + "simulcastStream": { + "width": 960, + "height": 540, + "fps": 24, + "bitrate": 1670 + } } } } - } -}' -``` - -### Response parameters - -**Headers** - -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| + }' + ``` + + + ```js + const url = `https://api.agora.io/${region}/v1/projects/${appId}/rtls/ingress/stream-templates/${templateId}`; -**Response body** + const data = { + settings: { + transcoding: { + video: { + enabled: true, + codec: "H.264", + width: 1280, + height: 720, + fps: 24, + bitrate: 2200, + simulcastStream: { + width: 960, + height: 540, + fps: 24, + bitrate: 1670 + } + } + } + } + }; -For details about possible response status codes, see [Response status codes](../../response-status-codes). + fetch(url, { + method: "PUT", + headers: { + "Content-Type": "application/json", + "Accept": "application/json", + "Authorization": "Basic " + }, + body: JSON.stringify(data) + }) + .then(response => response.json()) + .then(data => console.log("Success:", data)) + .catch(error => console.error("Error:", error)); -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. + ``` + + + ```python + url = f"https://api.agora.io/{region}/v1/projects/{appId}/rtls/ingress/stream-templates/{templateId}" -If the status code is `200`, the request succeeds, and the response body includes the following parameters: + headers = { + "Content-Type": "application/json", + "Accept": "application/json", + "Authorization": "Basic " + } -| Parameter | Type | Description | -| :--------------- | :----- | :----------------------------------------------------------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | + data = { + "settings": { + "transcoding": { + "video": { + "enabled": True, + "codec": "H.264", + "width": 1280, + "height": 720, + "fps": 24, + "bitrate": 2200, + "simulcastStream": { + "width": 960, + "height": 540, + "fps": 24, + "bitrate": 1670 + } + } + } + } + } -### Response example + response = requests.put(url, headers=headers, data=json.dumps(data)) -The following is a response example for a successful request: + print(response.status_code, response.json()) + ``` + + +
+
```json { "status": "success" } ``` - - \ No newline at end of file +
+ + diff --git a/shared/media-gateway/reference/rest-api/endpoints/message-notification-service/query-ip-address.mdx b/shared/media-gateway/reference/rest-api/endpoints/message-notification-service/query-ip-address.mdx index 27ff52859..1a7818cc4 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/message-notification-service/query-ip-address.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/message-notification-service/query-ip-address.mdx @@ -1,725 +1,111 @@ import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -When using Agora real-time audio and video, you can use the service to receive channel events. + -After activating the service, when a channel event occurs, the server will deliver the event notification to your message receiving server. + -If your server is behind a firewall, you need to call the IP address query API to retrieve the IP addresses of and configure your firewall to trust all these IP addresses. +When using Agora real-time audio and video, you can use the [ service](#ncs-service) to receive channel events. + Agora adjusts the IP addresses every 24 hours. Best practice is to call this endpoint at least every 24 hours and automatically update the firewall configuration. + -### Prototype - -* Method: `GET` -* Endpoint: `https://api.agora.io/v2/ncs/ip` - -### Request parameters - -**Authentication** - -- HTTP Basic Authentication - - Every time you send an HTTP request, you must pass in a credential in the `Authorization` field in the HTTP request header. See [RESTful Authentication](../../../restful-authentication#implement-basic-http-authentication) on how to generate it. - - Basic authentication is a simple authentication scheme built into the HTTP protocol. To use it, send your HTTP requests with an `Authorization` header that contains the word Basic followed by a space and a base64-encoded string `username:password`. - - Example: `Authorization: Basic ZGVtbzpwQDU1dzByZA==` - -### Request examples - -Use one of the following code examples to test this request: - -
-Shell - - -
- curl - - - {`curl --request GET \\ - --url http://api.sd-rtn.com/v2/ncs/ip \\ - --header 'Accept: application/json' \\ - --header 'Authorization: '`} - -
- - -
- HTTPie - - - {`http GET http://api.sd-rtn.com/v2/ncs/ip \\ - Accept:application/json \\ - Authorization:''`} - -
- - -
- wget - - - {`wget --quiet \\ - --method GET \\ - --header 'Authorization: ' \\ - --header 'Accept: application/json' \\ - --output-document \\ - - http://api.sd-rtn.com/v2/ncs/ip`} - -
-
- -
-Javascript - - -
- Fetch - - - {`const url = 'http://api.sd-rtn.com/v2/ncs/ip'; - const options = {method: 'GET', headers: {Authorization: '', Accept: 'application/json'}}; - - try { - const response = await fetch(url, options); - const data = await response.json(); - console.log(data); - } catch (error) { - console.error(error); - }`} - -
- - -
- XMLHTTPRequest - - - {`const data = null; - - const xhr = new XMLHttpRequest(); - xhr.withCredentials = true; - - xhr.addEventListener('readystatechange', function () { - if (this.readyState === this.DONE) { - console.log(this.responseText); - } - }); - - xhr.open('GET', 'http://api.sd-rtn.com/v2/ncs/ip'); - xhr.setRequestHeader('Authorization', ''); - xhr.setRequestHeader('Accept', 'application/json'); - - xhr.send(data);`} - -
- - -
- jQuery - - - {`const settings = { - async: true, - crossDomain: true, - url: 'http://api.sd-rtn.com/v2/ncs/ip', - method: 'GET', - headers: { - Authorization: '', - Accept: 'application/json' - } - }; - - $.ajax(settings).done(function (response) { - console.log(response); - });`} - -
- - -
- Axios - - - {`import axios from 'axios'; - - const options = { - method: 'GET', - url: 'http://api.sd-rtn.com/v2/ncs/ip', - headers: {Authorization: '', Accept: 'application/json'} - }; - - try { - const { data } = await axios.request(options); - console.log(data); - } catch (error) { - console.error(error); - }`} - -
-
- -
-Node - - -
- Native - - - {`const http = require('http'); - - const options = { - method: 'GET', - hostname: 'api.sd-rtn.com', - port: null, - path: '/v2/ncs/ip', - headers: { - Authorization: '', - Accept: 'application/json' - } - }; - - const req = http.request(options, function (res) { - const chunks = []; +### Request - res.on('data', function (chunk) { - chunks.push(chunk); - }); + + + + + - res.on('end', function () { - const body = Buffer.concat(chunks); - console.log(body.toString()); - }); - }); - req.end();`} - -
+### Response - -
- Request - - - {`const request = require('request'); - - const options = { - method: 'GET', - url: 'http://api.sd-rtn.com/v2/ncs/ip', - headers: {Authorization: '', Accept: 'application/json'} - }; - - request(options, function (error, response, body) { - if (error) throw new Error(error); - - console.log(body); - });`} - -
- - -
- Unirest - - - {`const unirest = require('unirest'); - - const req = unirest('GET', 'http://api.sd-rtn.com/v2/ncs/ip'); - - req.headers({ - Authorization: '', - Accept: 'application/json' - }); - - req.end(function (res) { - if (res.error) throw new Error(res.error); - - console.log(res.body); - });`} - -
- - -
- Fetch - - {`const fetch = require('node-fetch'); - - const url = 'http://api.sd-rtn.com/v2/ncs/ip'; - const options = {method: 'GET', headers: {Authorization: '', Accept: 'application/json'}}; - - try { - const response = await fetch(url, options); - const data = await response.json(); - console.log(data); - } catch (error) { - console.error(error); - }`} - -
- - -
- Axios - - - {`const axios = require('axios').default; - - const options = { - method: 'GET', - url: 'http://api.sd-rtn.com/v2/ncs/ip', - headers: {Authorization: '', Accept: 'application/json'} - }; - - try { - const { data } = await axios.request(options); - console.log(data); - } catch (error) { - console.error(error); - }`} - -
-
- -
-Python - - -
- Python 3 - - - {`import http.client +If the status code is `200`, the request succeeds, and the response body includes the following parameters: - conn = http.client.HTTPConnection("api.sd-rtn.com") + + + + + + The IP address of the server. When you receive a response, you need to add the IP address (or list of IP addresses) from this field to the whitelist. + + + + + - headers = { - 'Authorization': "", - 'Accept': "application/json" - } +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). - conn.request("GET", "/v2/ncs/ip", headers=headers) + +## Reference - res = conn.getresponse() - data = res.read() +This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product. - print(data.decode("utf-8"))`} - -
+### NCS service - -
- Requests +After activating the service, when a channel event occurs, the server will deliver the event notification to your message receiving server. - - {`import requests +If your server is behind a firewall, you need to call the IP address query API to retrieve the IP addresses of and configure your firewall to trust all these IP addresses. + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + + ```js + curl -X GET "http://api.sd-rtn.com/v2/ncs/ip" \ + -H "Authorization: Bearer YOUR_TOKEN_HERE" \ + -H "Accept: application/json" + ``` + + + ```js + fetch("http://api.sd-rtn.com/v2/ncs/ip", { + method: "GET", + headers: { + "Authorization": "Bearer YOUR_TOKEN_HERE", + "Accept": "application/json" + } + }) + .then(res => res.json()) + .then(console.log) + .catch(console.error); + ``` + + + ```python url = "http://api.sd-rtn.com/v2/ncs/ip" - headers = { - "Authorization": "", + "Authorization": "Bearer YOUR_TOKEN_HERE", "Accept": "application/json" } - response = requests.get(url, headers=headers) - - print(response.json())`} - -
-
- -
-Go - - - {`package main - - import ( - "fmt" - "net/http" - "io" - ) - - func main() { - - url := "http://api.sd-rtn.com/v2/ncs/ip" - - req, _ := http.NewRequest("GET", url, nil) - - req.Header.Add("Authorization", "") - req.Header.Add("Accept", "application/json") - - res, _ := http.DefaultClient.Do(req) - - defer res.Body.Close() - body, _ := io.ReadAll(res.Body) - - fmt.Println(res) - fmt.Println(string(body)) - - }`} - -
- -
-C - - {`CURL *hnd = curl_easy_init(); - -curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET"); -curl_easy_setopt(hnd, CURLOPT_URL, "http://api.sd-rtn.com/v2/ncs/ip"); - -struct curl_slist *headers = NULL; -headers = curl_slist_append(headers, "Authorization: "); -headers = curl_slist_append(headers, "Accept: application/json"); -curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers); - -CURLcode ret = curl_easy_perform(hnd);`} - -
- -
-Objective-C - - - {`#import - -NSDictionary *headers = @{ @"Authorization": @"", - @"Accept": @"application/json" }; - -NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http://api.sd-rtn.com/v2/ncs/ip"] - cachePolicy:NSURLRequestUseProtocolCachePolicy - timeoutInterval:10.0]; -[request setHTTPMethod:@"GET"]; -[request setAllHTTPHeaderFields:headers]; - -NSURLSession *session = [NSURLSession sharedSession]; -NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request - completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) { - if (error) { - NSLog(@"%@", error); - } else { - NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response; - NSLog(@"%@", httpResponse); - } - }]; -[dataTask resume];`} - -
- -
-OCaml - - - {`open Cohttp_lwt_unix -open Cohttp -open Lwt - -let uri = Uri.of_string "http://api.sd-rtn.com/v2/ncs/ip" in -let headers = Header.add_list (Header.init ()) [ - ("Authorization", ""); - ("Accept", "application/json"); -] in - -Client.call ~headers \`GET uri -\>\>= fun (res, body_stream) -\> - (* Do stuff with the result *)`} - -
- -
-C# - -
- HTTPClient - - - {`using System.Net.Http.Headers; - var client = new HttpClient(); - var request = new HttpRequestMessage - { - Method = HttpMethod.Get, - RequestUri = new Uri("http://api.sd-rtn.com/v2/ncs/ip"), - Headers = - { - { "Authorization", "" }, - { "Accept", "application/json" }, - }, - }; - using (var response = await client.SendAsync(request)) - { - response.EnsureSuccessStatusCode(); - var body = await response.Content.ReadAsStringAsync(); - Console.WriteLine(body); - }`} - -
- - -
- RestSharp - - - {`var client = new RestClient("http://api.sd-rtn.com/v2/ncs/ip"); - var request = new RestRequest(Method.GET); - request.AddHeader("Authorization", ""); - request.AddHeader("Accept", "application/json"); - IRestResponse response = client.Execute(request);`} - -
-
- - -
-Java - -
- AsyncHttp - - - {`AsyncHttpClient client = new DefaultAsyncHttpClient(); - client.prepare("GET", "http://api.sd-rtn.com/v2/ncs/ip") - .setHeader("Authorization", "") - .setHeader("Accept", "application/json") - .execute() - .toCompletableFuture() - .thenAccept(System.out::println) - .join(); - - client.close();`} - -
- - -
- NetHttp - - - {`HttpRequest request = HttpRequest.newBuilder() - .uri(URI.create("http://api.sd-rtn.com/v2/ncs/ip")) - .header("Authorization", "") - .header("Accept", "application/json") - .method("GET", HttpRequest.BodyPublishers.noBody()) - .build(); - HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString()); - System.out.println(response.body());`} - -
- - -
- OkHttp - - - {`OkHttpClient client = new OkHttpClient(); - - Request request = new Request.Builder() - .url("http://api.sd-rtn.com/v2/ncs/ip") - .get() - .addHeader("Authorization", "") - .addHeader("Accept", "application/json") - .build(); - - Response response = client.newCall(request).execute();`} - -
- - -
- Unirest - - - {`HttpResponse response = Unirest.get("http://api.sd-rtn.com/v2/ncs/ip") - .header("Authorization", "") - .header("Accept", "application/json") - .asString();`} - -
-
- -
-Http 1.1 - - - {`GET /v2/ncs/ip HTTP/1.1 -Authorization: -Accept: application/json -Host: api.sd-rtn.com`} - -
- -
-Clojure - - - {`(require '[clj-http.client :as client]) - -(client/get "http://api.sd-rtn.com/v2/ncs/ip" {:headers {:Authorization ""} - :accept :json})`} - -
- -
-Kotlin - - - {`val client = OkHttpClient() - -val request = Request.Builder() - .url("http://api.sd-rtn.com/v2/ncs/ip") - .get() - .addHeader("Authorization", "") - .addHeader("Accept", "application/json") - .build() - -val response = client.newCall(request).execute()`} - -
- -
-PHP - -
- cURL - - - {` "http://api.sd-rtn.com/v2/ncs/ip", - CURLOPT_RETURNTRANSFER => true, - CURLOPT_ENCODING => "", - CURLOPT_MAXREDIRS => 10, - CURLOPT_TIMEOUT => 30, - CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, - CURLOPT_CUSTOMREQUEST => "GET", - CURLOPT_HTTPHEADER => [ - "Accept: application/json", - "Authorization: " - ], - ]); - - $response = curl_exec($curl); - $err = curl_error($curl); - - curl_close($curl); - - if ($err) { - echo "cURL Error #:" . $err; - } else { - echo $response; - }`} - -
- - -
- Guzzle - - - {`request('GET', 'http://api.sd-rtn.com/v2/ncs/ip', [ - 'headers' => [ - 'Accept' => 'application/json', - 'Authorization' => '', - ], - ]); - - echo $response->getBody();`} - -
-
- -
-PowerShell - -
- WebRequest - - - {`$headers=@{} - $headers.Add("Authorization", "") - $headers.Add("Accept", "application/json") - $response = Invoke-WebRequest -Uri 'http://api.sd-rtn.com/v2/ncs/ip' -Method GET -Headers $headers`} - -
- - -
- RestMethod - - - {`$headers=@{} - $headers.Add("Authorization", "") - $headers.Add("Accept", "application/json") - $response = Invoke-RestMethod -Uri 'http://api.sd-rtn.com/v2/ncs/ip' -Method GET -Headers $headers`} - -
-
- -
-R - - - {`library(httr) - -url <- "http://api.sd-rtn.com/v2/ncs/ip" - -response <- VERB("GET", url, add_headers('Authorization' = ''), content_type("application/octet-stream"), accept("application/json")) - -content(response, "text")`} - -
- -
-Ruby - - {`require 'uri' -require 'net/http' - -url = URI("http://api.sd-rtn.com/v2/ncs/ip") - -http = Net::HTTP.new(url.host, url.port) - -request = Net::HTTP::Get.new(url) -request["Authorization"] = '' -request["Accept"] = 'application/json' - -response = http.request(request) -puts response.read_body`} - -
- -
-Swift - - {`import Foundation - -let headers = [ - "Authorization": "", - "Accept": "application/json" -] - -let request = NSMutableURLRequest(url: NSURL(string: "http://api.sd-rtn.com/v2/ncs/ip")! as URL, - cachePolicy: .useProtocolCachePolicy, - timeoutInterval: 10.0) -request.httpMethod = "GET" -request.allHTTPHeaderFields = headers - -let session = URLSession.shared -let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in - if (error != nil) { - print(error as Any) - } else { - let httpResponse = response as? HTTPURLResponse - print(httpResponse) - } -}) - -dataTask.resume()`} - -
- -### Response parameters - -For details about possible response status codes, see [Response status codes](../../response-status-code). - -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. - -If the status code is `200`, the request succeeds, and the response body includes the following parameters: - -| Parameter | Type | Description | -| :-------- | :------ | :----------------------------------------------------------- | -| `data` | Object |
  • `service`
    • `hosts`
      • `primaryIP`: The IP address of the server. When you receive a response, you need to add the IP address (or list of IP addresses) from this field to the whitelist.
| - -### Response example - - - {`{ + res = requests.get(url, headers=headers) + print(res.json() if res.status_code == 200 else res.text) + ``` + + + +
+```json +{ "data": { "service": { "hosts": [ @@ -728,8 +114,9 @@ If the status code is `200`, the request succeeds, and the response body include } ] } - } -}`} - - - \ No newline at end of file + }` +} +``` +
+ + diff --git a/shared/media-gateway/reference/rest-api/endpoints/streaming-information/force-disconnection.mdx b/shared/media-gateway/reference/rest-api/endpoints/streaming-information/force-disconnection.mdx index e08f069fd..9e17c330e 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/streaming-information/force-disconnection.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/streaming-information/force-disconnection.mdx @@ -1,80 +1,152 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -This method disconnects an ongoing stream based on SID. - -### Prototype - -- Method: `DELETE` -- Endpoint: `https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/online-streams/:sid` + -You can combine this method with [deleting the streaming key](../streaming-key/delete-streaming-key) to implement the function of disabling the stream. Deleting the streaming key only removes it from the database. You can no longer use the streaming key, but you cannot disconnect the ongoing push. To disconnect, use one of the following methods: - -1. Call to [delete the streaming key](../streaming-key/delete-streaming-key) and then call this method to disconnect the ongoing push. + - Make sure to delete the streaming key first; otherwise, after using this API to force a disconnection, the push software will immediately reconnect. A new push session, corresponding to a new SID, will be generated, and the disconnection will fail. +This method disconnects an ongoing stream based on SID. -1. Call to [kick the user out of the channel](/video-calling/reference/channel-management-rest-api). This API can also force the user to disconnect. If the kicking API has been integrated, you can continue to use it to disconnect the stream. +Combine this API with [deleting the streaming key](../streaming-key/delete-streaming-key) to disable a stream. For more details, see [Disable a stream](#disable-a-stream). +### Request -### Request parameters +**Path parameters** -**Authentication** + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • `na`: North America
    • +
  • `eu`: Europe
    • +
  • `ap`: Asia, except mainland China
    • +
  • `cn`: Mainland China
    • +
+ + Make sure that: +
    +
  • The `region` value is the same as for the input source stream.
    • +
  • The domain names for setting the `region` parameter and streaming are the same.
    • +
  • The `region` value is in lowercase.
    • +
+ + + + The streaming session ID is the unique identifier for each initiated streaming task. It can be obtained by [querying the streaming list](query-streaming-list) or receiving the payload of the [message notification callback](../../../../develop/receive-notifications). + - +**Headers** -**Path parameters** + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + + + + -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `region` | String | Required | Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
| -| `sid` | String | Required | The streaming session ID is the unique identifier for each initiated streaming task. It can be obtained by [querying the streaming list](query-streaming-list) or receiving the payload of the [message notification callback](../../../../develop/receive-notifications).| +### Response **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + -### Request example - -```shell -curl --request DELETE \ - --url https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams/sid \ - --header 'Accept: application/json' \ - --header 'Authorization: Basic 123' \ - --header 'X-Request-ID: ' -``` +**Response body** -### Response parameters +If the status code is `200`, the request succeeds, and the response body includes the following parameters: -**Headers** + + + The status of this request. success means the request succeeds. + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| + -**Response body** +## Reference -For details about possible response status codes, see [Response status codes](../../response-status-codes). +### Disable a stream -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. +You can combine this method with [deleting the streaming key](../streaming-key/delete-streaming-key) to implement the function of disabling the stream. Deleting the streaming key only removes it from the database. You can no longer use the streaming key, but you cannot disconnect the ongoing push. To disconnect, use one of the following methods: -If the status code is `200`, the request succeeds, and the response body includes the following parameters: +1. Call to [delete the streaming key](../streaming-key/delete-streaming-key) and then call this method to disconnect the ongoing push. -| Parameter | Type | Description | -| :--------------- | :----- | :----------------------------------------------------------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | + Make sure to delete the streaming key first; otherwise, after using this API to force a disconnection, the push software will immediately reconnect. A new push session, corresponding to a new SID, will be generated, and the disconnection will fail. -### Response example +1. Call to [kick the user out of the channel](/video-calling/reference/channel-management-rest-api). This API can also force the user to disconnect. If the kicking API has been integrated, you can continue to use it to disconnect the stream. -The following is a response example for a successful request: + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + ```shell + curl --request DELETE \ + --url https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams/sid \ + --header 'Accept: application/json' \ + --header 'Authorization: Basic 123' \ + --header 'X-Request-ID: ' + ``` + + + ```js + fetch('https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams/sid', { + method: 'DELETE', + headers: { + 'Accept': 'application/json', + 'Authorization': 'Basic 123', + 'X-Request-ID': '' + } + }) + .then(res => res.text()) + .then(console.log) + .catch(console.error); + ``` + + + ```python + url = 'https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams/sid' + headers = { + 'Accept': 'application/json', + 'Authorization': 'Basic 123', + 'X-Request-ID': '' + } + + response = requests.delete(url, headers=headers) + print(response.status_code) + ``` + + + +
+
```json { "status" : "string" } ``` - - \ No newline at end of file +
+ + diff --git a/shared/media-gateway/reference/rest-api/endpoints/streaming-information/mute.mdx b/shared/media-gateway/reference/rest-api/endpoints/streaming-information/mute.mdx index 265cf8515..ee8d93bd6 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/streaming-information/mute.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/streaming-information/mute.mdx @@ -1,78 +1,106 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -Use this method to mute or unmute the current streaming. - -### Prototype + -- Method: `POST` -- Endpoint: `https://api.sd-rtn.com/:region/:version/projects/:appId/rtls/ingress/online-streams/mute/:sid` + -### Request parameters -**Authentication** +Use this method to mute or unmute the current streaming. - +### Request **Path parameters** -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `region` | String | Required | Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
 | -| `version` | String | Required | The API version. Use `v1`. | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `sid` | String | Required | The streaming session ID is the unique identifier for each initiated streaming task. It can be obtained by [querying the streaming list](query-streaming-list) or receiving the payload of the [message notification callback](/media-gateway/develop/receive-notifications).| + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • na: North America
    • +
  • eu: Europe
    • +
  • ap: Asia, except mainland China
    • +
  • cn: Mainland China
    • +
+ + Make sure that: +
    +
  • The region value is the same as for the input source stream.
    • +
  • The domain names for setting the region parameter and streaming are the same.
    • +
  • The region value is in lowercase.
    • +
+ + +The API version. Use `v1`. + + +The streaming session ID is the unique identifier for each initiated streaming task. It can be obtained by [querying the streaming list](query-streaming-list) or receiving the payload of the [message notification callback](/media-gateway/develop/receive-notifications). + + **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + + + + **Request body** The request body consists of a JSON Object type `settings` and includes the following fields: - -| Parameter | Data type | Required/Optional | Description | -| :------------ | :-------- |:----------------- | :---------------------- | -|`videoMuted` | boolean | Required | Whether to mute the video stream:
  • `true`: Mute pushing the video stream.
  • `false`: Unmute pushing the video stream.
| -|`audioMuted` | boolean | Required | Whether to mute the audio stream:
  • `true`: Mute pushing the audio stream.
  • `false`: Unmute pushing the audio stream.
| - -### Request example - -```shell -curl --request post \ - --url https://api.sd-rtn.com/:region/:version/projects/:appId/rtls/ingress/online-streams/mute/:sid \ - --header 'Authorization: Basic ' \ - --header 'X-Request-ID: ' \ - --data ' -{ - "settings": { - "videoMuted": true, - "audioMuted": false - } -}' -``` - -### Response parameters + + + Whether to mute the video stream: +
    +
  • true: Mute pushing the video stream.
    • +
  • false: Unmute pushing the video stream.
    • +
+ + + + Whether to mute the audio stream: +
    +
  • true: Mute pushing the audio stream.
    • +
  • false: Unmute pushing the audio stream.
    • +
+ + + +### Response **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + **Response body** -For details about possible response status codes, see [Response status codes](../../response-status-codes). - -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. - If the status code is `200`, the request succeeds, and the response body includes the following parameters: -| Parameter | Type | Description | -| :--------------- | :----- | :----------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | + + + The status of this request. success means the request succeeds. + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). - The successful execution of this request only confirms that the command is sent to the gateway node handling the stream; it does not guarantee that the mute/unmute operation was successful. The operation is executed asynchronously in the background. @@ -82,16 +110,80 @@ If the status code is `200`, the request succeeds, and the response body include - By default, each stream starts unmuted (audio and video are published normally). Each API call applies to the current stream. If the streamer disconnects and restarts the stream, the new stream resets to the initial unmuted state. -### Response example - -The following is a response example for a successful request: + +To explore the RESTful API parameters, obtain sample code in various client languages, or test requests, refer to the [Postman API reference](https://documenter.getpostman.com/view/6319646/SVSLr9AM#0e9f38c1-8942-499d-9394-1e87466b326a). + + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + ```shell + curl --request post \ + --url https://api.sd-rtn.com/:region/:version/projects/:appId/rtls/ingress/online-streams/mute/:sid \ + --header 'Authorization: Basic ' \ + --header 'X-Request-ID: ' \ + --data ' + { + "settings": { + "videoMuted": true, + "audioMuted": false + } + }' + ``` + + + ```js + fetch("https://api.sd-rtn.com/your-region/your-version/projects/your-appId/rtls/ingress/online-streams/mute/your-sid", { + method: "POST", + headers: { + "Content-Type": "application/json", + "Authorization": "Basic ", + "X-Request-ID": "" + }, + body: JSON.stringify({ + settings: { + videoMuted: true, + audioMuted: false + } + }) + }) + .then(res => res.json()) + .then(console.log) + .catch(console.error); + ``` + + + ```python + url = "https://api.sd-rtn.com/your-region/your-version/projects/your-appId/rtls/ingress/online-streams/mute/your-sid" + headers = { + "Content-Type": "application/json", + "Authorization": "Basic ", + "X-Request-ID": "" + } + data = { + "settings": { + "videoMuted": True, + "audioMuted": False + } + } + + res = requests.post(url, headers=headers, json=data) + ``` + + + +
+
```json { "status": "success" } ``` - - -To explore the RESTful API parameters, obtain sample code in various client languages, or test requests, refer to the [Postman API reference](https://documenter.getpostman.com/view/6319646/SVSLr9AM#0e9f38c1-8942-499d-9394-1e87466b326a). - \ No newline at end of file +
+ + diff --git a/shared/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-information.mdx b/shared/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-information.mdx index 966f44a27..ee60a7a98 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-information.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-information.mdx @@ -1,73 +1,184 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -This method queries an ongoing push based on SID. - -### Prototype + -- Method: `GET` -- Endpoint: `https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/online-streams/:sid` + -### Request parameters - -**Authentication** +This method queries an ongoing push based on SID. - +### Request **Path parameters** -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `region` | String | Required | Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
| -| `sid` | String | Required | The streaming session ID is the unique identifier for each initiated streaming task. It can be obtained by [querying the streaming list](query-streaming-list) or receiving the payload of the [message notification callback](../../../../develop/receive-notifications).| + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • `na`: North America
    • +
  • `eu`: Europe
    • +
  • `ap`: Asia, except mainland China
    • +
  • `cn`: Mainland China
    • +
+ + Make sure that: +
    +
  • The `region` value is the same as for the input source stream.
    • +
  • The domain names for setting the `region` parameter and streaming are the same.
    • +
  • The `region` value is in lowercase.
    • +
+ + + + The streaming session ID is the unique identifier for each initiated streaming task. It can be obtained by [querying the streaming list](query-streaming-list) or receiving the payload of the [message notification callback](../../../../develop/receive-notifications). + -**Headers** - -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | -### Request example +**Headers** -```shell -curl --request GET \ - --url https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams/sid \ - --header 'Accept: application/json' \ - --header 'Authorization: Basic 123' \ - --header 'X-Request-ID: ' -``` + + + The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. + + + + + -### Response parameters +### Response **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| + + + The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. + + **Response body** -For details about possible response status codes, see [Response status codes](../../response-status-codes). - -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. - If the status code is `200`, the request succeeds, and the response body includes the following parameters: + + + The status of this request. success means the request succeeds. + + + + Includes the following fields: + + A streaming session ID. A unique sid will be generated for each stream. + + + The name of the channel associated with the streaming key. + + + The user UID in the channel associated with the streaming key. + + + The push address in the $domain/live/$streamkey format. + + + The flow status. Possible values are: +
    +
  • "Started": Connection has been established, waiting to stream audio and video.
    • +
  • "Running": Is being streamed.
    • +
+ + + + + Streaming start time in the "2024-01-01 01:01:01.001" format. + + + + The source stream bitrate (audio + video) of the pushed stream, in Kbps. + + + + Video stream parameters, returned only if the status is "Running": + + Video width in pixels. + + + Video height in pixels. + + + Video frame rate in frames per second. + + + + + Audio stream parameters, returned only if the status is "Running": + + The number of audio channels. + + + Audio sampling rate in Hz. + + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). -| Parameter | Type | Description | -| :--------------- | :----- | :----------------------------------------------------------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | -| `data` | Object | Includes the following fields:
  • `sid`: String, a streaming session ID. A unique `sid` will be generated for each stream.
  • `channel`: String. The name of the channel associated with the streaming key.
  • `uid`: String, the user UID in the channel associated with the streaming key.
  • `url`: String, the push address in the `$domain/live/$streamkey` format.
  • `status`: String, the flow status. Possible values are the following:
    • `"Started"`: Connection has been established, waiting to stream audio and video.
      • `"Running"`: Is being streamed.
| -| `beginAt` | String | Streaming start time in the "2024-01-01 01:01:01.001" format. | -| `bitrate` | Integer | The source stream bitrate (audio + video) of the pushed stream, in Kbps.| -| `video` | Object | Video stream parameters, returned only if the status is `"Running"`:
  • `width`: Number, video width in pixels.
  • `height`: Number, video height in pixels.
  • `fps`: Video frame rate in frames per second.
| -| `audio` | Object | Audio stream parameters, returned only if the status is `"Running"`:
  • `channels`: Number, the number of audio channels.
  • `sampleRate`: Number, audio sampling rate in Hz.
| - -### Response example - -The following is a response example for a successful request: + + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + ```shell + curl --request GET \ + --url https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams/sid \ + --header 'Accept: application/json' \ + --header 'Authorization: Basic 123' \ + --header 'X-Request-ID: ' + ``` + + + ```js + fetch("https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams", { + method: "GET", + headers: { + "Accept": "application/json", + "Authorization": "Basic 123", + "X-Request-ID": "" + } + }) + .then(res => res.json()) + .then(console.log) + .catch(console.error); + ``` + + + ```python + url = "https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams" + headers = { + "Accept": "application/json", + "Authorization": "Basic 123", + "X-Request-ID": "" + } + res = requests.get(url, headers=headers) + ``` + + +
+
```json { "status" : "string" , @@ -93,5 +204,6 @@ The following is a response example for a successful request: ] } ``` - - +
+ + diff --git a/shared/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-list.mdx b/shared/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-list.mdx index 96874932c..bc876b589 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-list.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/streaming-information/query-streaming-list.mdx @@ -1,86 +1,165 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -This method queries a streaming key information, such as the associated UID, channel name, validity period, and so on. - -### Prototype + -- Method: `GET` -- Endpoint: `https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/online-streams?channel={channel}` + -### Request parameters - -**Authentication** +This method queries a streaming key information, such as the associated UID, channel name, validity period, and so on. - +### Request **Path parameters** -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `region` | String | Required | Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
| + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • na: North America
    • +
  • eu: Europe
    • +
  • ap: Asia, except mainland China
    • +
  • cn: Mainland China
    • +
+ + Make sure that: +
    +
  • The region value is the same as for the input source stream.
    • +
  • The domain names for setting the region parameter and streaming are the same.
    • +
  • The region value is in lowercase.
    • +
+ + **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | + + + The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. + + + + + **Query parameters** -| Parameter | Data type | Required/Optional | Description | -| :-------- | :-------- | :---------------- | :---------- | -| `channel` | String | Optional. | The channel name. If you specify a channel, the response only contains the information of the streaming list in the specified channel. Since Agora's `channelName` supports special characters, the channel name must be URL encoded first. + + + The channel name. If you specify a channel, the response only contains the information of the streaming list in the specified channel. Since Agora's `channelName` supports special characters, the channel name must be URL encoded first. + + -### Request example +### Response -```shell -curl --request GET \ - --url https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams \ - --header 'Accept: application/json' \ - --header 'Authorization: Basic 123' \ - --header 'X-Request-ID: ' -``` - -### Response parameters - -**Headers** - -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + **Response body** -For details about possible response status codes, see [Response status codes](../../response-status-codes). - -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. - If the status code is `200`, the request succeeds, and the response body includes the following parameters: -| Parameter | Type | Description | -| :--------------- | :----- | :----------------------------------------------------------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | -| `data` | Object | Includes the following fields:
  • `streamKey`: String, the queried streaming key.
  • `channel`: String. The name of the channel associated with the streaming key.
  • `uid`: String, the user UID in the channel associated with the streaming key.
  • `expiresAfter`: Integer, the validity period of the streaming key from the time of creation, in seconds.
  • `createdAt`: String, the Unix timestamp for when the streaming key was created, in seconds.
| - -### Response example - -The following is a response example for a successful request: - + + + The status of this request. success means the request succeeds. + + + + Includes the following fields: + + The queried streaming key. + + + The name of the channel associated with the streaming key. + + + The user UID in the channel associated with the streaming key. + + + The validity period of the streaming key from the time of creation, in seconds. + + + The Unix timestamp for when the streaming key was created, in seconds. + + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). + + + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + ```shell + curl --request GET \ + --url https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams \ + --header 'Accept: application/json' \ + --header 'Authorization: Basic 123' \ + --header 'X-Request-ID: ' + ``` + + + ```js + fetch("https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams", { + method: "GET", + headers: { + "Accept": "application/json", + "Authorization": "Basic 123", + "X-Request-ID": "" + } + }) + .then(res => res.json()) + .then(console.log) + .catch(console.error); + ``` + + + ```python + url = "https://api.agora.io/region/v1/projects/appId/rtls/ingress/online-streams" + headers = { + "Accept": "application/json", + "Authorization": "Basic 123", + "X-Request-ID": "" + } + + res = requests.get(url, headers=headers) + ``` + + +
+
```json { "status" : "success" , "data" : { "streamKey" : "2dfMTR****fys" , "channel" : "shx001" , - "uid" : "1001" , + "uid" : "1001" ,` "expiresAfter" : 0 , "createdAt" : "1686820170" } } ``` - - \ No newline at end of file +
+ + diff --git a/shared/media-gateway/reference/rest-api/endpoints/streaming-key/create-streaming-key.mdx b/shared/media-gateway/reference/rest-api/endpoints/streaming-key/create-streaming-key.mdx index a69cab581..ca70b5e55 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/streaming-key/create-streaming-key.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/streaming-key/create-streaming-key.mdx @@ -1,90 +1,206 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -This method creates a streaming key. + -### Prototype + -- Method: `POST` -- Endpoint: `https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/streamkeys` - -Create a key before streaming to ensure that the media stream is pushed to the correct channel and under the correct host ID. +This method creates a streaming key to ensure the media stream is pushed to the correct channel and host ID. Keep the created streaming key secure to prevent unauthorized streaming to the channel. -### Request parameters - -**Authentication** - - +### Request **Path parameters** -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `region` | String | Required | Create an area for pushing the stream key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
| + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the stream key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • `na`: North America
    • +
  • `eu`: Europe
    • +
  • `ap`: Asia, except mainland China
    • +
  • `cn`: Mainland China
    • +
+ + Make sure that: +
    +
  • The `region` value is the same as for the input source stream.
    • +
  • The domain names for setting the `region` parameter and streaming are the same.
    • +
  • The `region` value is in lowercase.
    • +
+ + + **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | + + + The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign X-Request-ID a value. If no value is assigned, the Agora server will automatically generate a UUID and pass it in. + + + + + **Request body** The request body consists of a JSON Object type `settings` and includes the following fields: -| Parameter | Data type | Required/Optional | Description | -| :------------ | :-------- |:----------------- | :---------------------- | -|`channel` | String | Required | The channel name. The string length must be less than 64 bytes. The following character sets are supported (89 characters in total):
  • All lowercase English letters (a-z)
  • All uppercase English letters (AZ)
  • Numbers 0-9
  • Space
  • `!`, `#`, `$`, `%`, `&`, `(`, `)`, `+`, `-`, `:`, `;`, `<`, `=`, `.`, `>`, `?`, `@`, `[`, `]`, `^`, `_`, `{`, `}`, `\|`, `~`, `,`.
You can leave this field empty. A random integer UID will be used to enter the channel, in the format of `"GR-xxxx"`. The specific UID value can be obtained by [querying the streaming list](../streaming-information/query-streaming-list) or [receiving notifications about events](../../../../develop/receive-notifications).| -|`uid` | String | Required | The host user UID in the channel. Can be a numeric ID or a string ID. For numeric IDs, the value range is from 1 to 232 -1, that is, 4294967295. A greater value will be recognized as a string. For string IDs, the value cannot exceed 255 bytes or be empty. The following character sets are supported (89 characters in total):
  • All lowercase English letters (a-z)
  • All uppercase English letters (AZ)
  • Numbers 0-9
  • Space
  • `!`, `#`, `$`, `%`, `&`, `(`, `)`, `+`, `-`, `:`, `;`, `<`, `=`, `.`, `>`, `?`, `@`, `[`, `]`, `^`, `_`, `{`, `}`, `\|`, `~`, `,`.
You can leave this field empty or pass in `0`. A random integer UID will be used to enter the channel. The specific UID value can be obtained by [querying the streaming list](../streaming-information/query-streaming-list) or [receiving notifications about events](../../../../develop/receive-notifications). The `channel` and `uid` parameters cannot be empty or `0` at the same time. Examples of the entered `uid` values and the actual ID values:
  • `"123"` - integer UID, `123`
  • `"0123"` - integer UID, `123`
  • `"4294967295"` - integer UID, `4294967295`,
  • `"4294967296"` - string UID, `"4294967296"`,
  • `"123abc"` - string UID, `"123abc"`.
| -|`expiresAfter` | Number | Required | The validity period of the created streaming key in seconds, from the time of creation. If set to `0`, the streaming key will always be valid. To ensure a successful request, do not leave this field empty or set to null.| -|`templateId` | String | Optional | The associated flow configuration template ID. For details, see [template API documentation](../flow-configuration-template/create-reset-template). Do not provide this field if you have not created a configuration template. If not provided, the default configuration will be used.| - -### Request example - -```shell -curl --request POST \ - --url https://api.sd-rtn.com/region/v1/projects/yourActualAppId/rtls/ingress/streamkeys \ - --header 'Accept: application/json' \ - --header 'Authorization: Basic ' \ - --header 'Content-Type: application/json' \ - --header 'X-Request-ID: ' \ - --data '{ - "settings": { - "channel": "shx001", - "uid": "1001", - "expiresAfter": 0 - } -}' -``` + + + The channel name. The string length must be less than 64 bytes. The following character sets are supported (89 characters in total):
  • All lowercase English letters (a-z)
  • All uppercase English letters (AZ)
  • Numbers 0-9
  • Space
  • `!`, `#`, `$`, `%`, `&`, `(`, `)`, `+`, `-`, `:`, `;`, `<`, `=`, `.`, `>`, `?`, `@`, `[`, `]`, `^`, `_`, `{`, `}`, `\|`, `~`, `,`.
You can leave this field empty. A random integer UID will be used to enter the channel, in the format of `"GR-xxxx"`. The specific UID value can be obtained by [querying the streaming list](../streaming-information/query-streaming-list) or [receiving notifications about events](../../../../develop/receive-notifications). + -### Response parameters + + The host user UID in the channel. Can be a numeric ID or a string ID. For numeric IDs, the value range is from 1 to 232 -1, that is, 4294967295. A greater value will be recognized as a string. For string IDs, the value cannot exceed 255 bytes or be empty. The following character sets are supported (89 characters in total):
  • All lowercase English letters (a-z)
  • All uppercase English letters (AZ)
  • Numbers 0-9
  • Space
  • `!`, `#`, `$`, `%`, `&`, `(`, `)`, `+`, `-`, `:`, `;`, `<`, `=`, `.`, `>`, `?`, `@`, `[`, `]`, `^`, `_`, `{`, `}`, `\|`, `~`, `,`.
You can leave this field empty or pass in `0`. A random integer UID will be used to enter the channel. The specific UID value can be obtained by [querying the streaming list](../streaming-information/query-streaming-list) or [receiving notifications about events](../../../../develop/receive-notifications). The `channel` and `uid` parameters cannot be empty or `0` at the same time. Examples of the entered `uid` values and the actual ID values:
  • `"123"` - integer UID, `123`
  • `"0123"` - integer UID, `123`
  • `"4294967295"` - integer UID, `4294967295`,
  • `"4294967296"` - string UID, `"4294967296"`,
  • `"123abc"` - string UID, `"123abc"`.
+ -**Headers** + + The validity period of the created streaming key in seconds, from the time of creation. If set to `0`, the streaming key will always be valid. + + To ensure a successful request, do not leave this field empty or set to null. + + -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| + + The associated flow configuration template ID. For details, see [template API documentation](../flow-configuration-template/create-reset-template). Do not provide this field if you have not created a configuration template. If not provided, the default configuration will be used. + + -**Response body** -For details about possible response status codes, see [Response status codes](../../response-status-codes). +### Response -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. +**Headers** -If the status code is `200`, the request succeeds, and the response body includes the following parameters: + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + -| Parameter | Type | Description | -| :--------------- | :----- | :----------------------------------------------------------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | -| `data` | Object | Includes the following fields:
  • `streamKey`: String, the newly created streaming key.
  • `channel`: String. The name of the channel associated with the streaming key.
  • `uid`: String, the user UID in the channel associated with the streaming key.
  • `expiresAfter`: Integer, the validity period of the streaming key from the time of creation, in seconds.
  • `createdAt`: String, the Unix timestamp for when the streaming key was created, in seconds.
| +**Response body** -### Response example +If the status code is `200`, the request succeeds, and the response body includes the following parameters: -The following is a response example for a successful request: + + + The status of this request. `success` means the request succeeds. + + + Includes the following fields: + + The newly created streaming key. + + + The name of the channel associated with the streaming key. + + + The user UID in the channel associated with the streaming key. + + + Integer, the validity period of the streaming key from the time of creation, in seconds. + + + The Unix timestamp for when the streaming key was created, in seconds. + + + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). + + + + + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + + ```shell + curl --request POST \ + --url https://api.sd-rtn.com/region/v1/projects/yourActualAppId/rtls/ingress/streamkeys \ + --header 'Accept: application/json' \ + --header 'Authorization: Basic ' \ + --header 'Content-Type: application/json' \ + --header 'X-Request-ID: ' \ + --data '{ + "settings": { + "channel": "shx001", + "uid": "1001", + "expiresAfter": 0 + } + }' + ``` + + + ```js + fetch("https://api.sd-rtn.com/region/v1/projects/yourActualAppId/rtls/ingress/streamkeys", { + method: "POST", + headers: { + "Accept": "application/json", + "Authorization": "Basic ", + "Content-Type": "application/json", + "X-Request-ID": "" + }, + body: JSON.stringify({ + settings: { + channel: "shx001", + uid: "1001", + expiresAfter: 0 + } + }) + }) + .then(response => response.json()) + .then(data => console.log(data)) + .catch(error => console.error("Error:", error)); + ``` + + + ```python + url = "https://api.sd-rtn.com/region/v1/projects/yourActualAppId/rtls/ingress/streamkeys" + + headers = { + "Accept": "application/json", + "Authorization": "Basic ", + "Content-Type": "application/json", + "X-Request-ID": "" + } + + data = { + "settings": { + "channel": "shx001", + "uid": "1001", + "expiresAfter": 0 + } + } + + response = requests.post(url, headers=headers, json=data) + + print(response.status_code, response.json()) + ``` + + +
+
```json { @@ -98,5 +214,7 @@ The following is a response example for a successful request: } } ``` +
+ - \ No newline at end of file + diff --git a/shared/media-gateway/reference/rest-api/endpoints/streaming-key/delete-streaming-key.mdx b/shared/media-gateway/reference/rest-api/endpoints/streaming-key/delete-streaming-key.mdx index 8e44dc6e0..30c117621 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/streaming-key/delete-streaming-key.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/streaming-key/delete-streaming-key.mdx @@ -1,72 +1,139 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -This method deletes a streaming key. - -### Prototype - -- Method: `DELETE` -- Endpoint: `https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/streamkeys/:streamkey` + -Call to delete unused streaming keys. After a streaming key is deleted, you can no longer use it to push streams. If the deleted streaming key is still in use, the ongoing stream is not affected. To disable the ongoing stream immediately, use the SID to [force a disconnection](../streaming-information/force-disconnection). + -This API can also be used to revoke streaming keys generated by a script. For a complete key revocation, make sure to call this API across all configured regions. +This method deletes a streaming key. -### Request parameters + +- After a streaming key is deleted, you can no longer use it to push streams. If the deleted streaming key is still in use, the ongoing stream is not affected. To disable the ongoing stream immediately, use the SID to [force a disconnection](../streaming-information/force-disconnection). -**Authentication** +- This API can also be used to revoke streaming keys generated by a script. For a complete key revocation, make sure to call this API across all configured regions. + - +### Request **Path parameters** -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `region` | String | Required | Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
| -|`streamkey` | String | Required | The streaming key to be deleted.| + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • `na`: North America
    • +
  • `eu`: Europe
    • +
  • `ap`: Asia, except mainland China
    • +
  • `cn`: Mainland China
    • +
+ + Make sure that: +
    +
  • The `region` value is the same as for the input source stream.
    • +
  • The domain names for setting the `region` parameter and streaming are the same.
    • +
  • The `region` value is in lowercase.
    • +
+ + + + The streaming key to be deleted. + **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | - -### Request example + + + The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. + + + + + -```shell -curl --location -g --request DELETE 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/streamkeys/{{streamKey}}' -``` -### Response parameters +### Response **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + **Response body** -For details about possible response status codes, see [Response status codes](../../response-status-codes). - -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. - If the status code is `200`, the request succeeds, and the response body includes the following parameters: -| Parameter | Type | Description | -| :--------------- | :----- | :----------------------------------------------------------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | - -### Response example - -The following is a response example for a successful request: - + + + The status of this request. `success` means the request succeeds. + + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). + + + + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + ```shell + curl --location -g --request DELETE 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/streamkeys/{{streamKey}}' + ``` + + + ```js + fetch(`https://api.agora.io/${region}/v1/projects/${appId}/rtls/ingress/streamkeys/${streamKey}`, { + method: "DELETE", + headers: { + "Accept": "application/json", + "Authorization": "Basic " + } + }) + .then(response => response.json()) + .then(data => console.log(data)) + .catch(error => console.error("Error:", error)); + ``` + + + ```python + url = f"https://api.agora.io/{region}/v1/projects/{appId}/rtls/ingress/streamkeys/{streamKey}" + + headers = { + "Accept": "application/json", + "Authorization": "Basic " + } + + response = requests.delete(url, headers=headers) + ``` + + +
+
```json { "status": "success" "success" } ``` - - \ No newline at end of file +
+ + diff --git a/shared/media-gateway/reference/rest-api/endpoints/streaming-key/query-streaming-key-information.mdx b/shared/media-gateway/reference/rest-api/endpoints/streaming-key/query-streaming-key-information.mdx index ff399790f..5d0789dfc 100644 --- a/shared/media-gateway/reference/rest-api/endpoints/streaming-key/query-streaming-key-information.mdx +++ b/shared/media-gateway/reference/rest-api/endpoints/streaming-key/query-streaming-key-information.mdx @@ -1,66 +1,147 @@ import Authorization from '@docs/shared/media-gateway/reference/rest-api/authorization.mdx'; import CodeBlock from '@theme/CodeBlock'; import PostmanLink from '@docs/shared/media-gateway/reference/rest-api/postman-link.mdx'; +import RestAPILayout from '@site/src/components/rest-api/RestAPILayout'; +import LeftColumn from '@site/src/components/rest-api/LeftColumn'; +import RightColumn, { Section } from '@site/src/components/rest-api/RightColumn'; +import ParameterList, { Parameter } from '@site/src/components/rest-api/ParameterList'; +import PathParameter from '@site/src/components/rest-api/PathParameter'; +import { Tabs, TabItem } from '@site/src/components/rest-api/Tabs'; -This method queries a streaming key information, such as the associated UID, channel name, validity period, and so on. - -### Prototype - -- Method: `GET` -- Endpoint: `https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/streamkeys/:streamkey` + -### Request parameters + -**Authentication** +This method queries a streaming key information, such as the associated UID, channel name, validity period, and so on. - +### Request **Path parameters** -| Parameter | Data type | Required/Optional | Description | -| :---------- | :------- |:----------------- | :---------------------- | -| `appId` | String | Required | The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. | -| `region` | String | Required | Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported:
  • `na`: North America
  • `eu`: Europe
  • `ap`: Asia, except mainland China
  • `cn`: Mainland China
Make sure that:
  • The `region` value is the same as for the input source stream.
  • The domain names for setting the `region` parameter and streaming are the same.
  • The `region` value is in lowercase.
| -| `streamkey` | String | Required | The streaming key for which you need information.| + + The app ID provided by to each developer. After creating a project in , you can get an app ID. The app ID is a unique identifier for a project. + + + Create an area for pushing the streaming key. supports creation of stream keys by region. Currently, the following regions are supported: +
    +
  • `na`: North America
    • +
  • `eu`: Europe
    • +
  • `ap`: Asia, except mainland China
    • +
  • `cn`: Mainland China
    • +
+ + Make sure that: +
    +
  • The `region` value is the same as for the input source stream.
    • +
  • The domain names for setting the `region` parameter and streaming are the same.
    • +
  • The `region` value is in lowercase.
    • +
+ + + + The streaming key for which you need information. + **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign `X-Request-ID` a value. If no value is assigned, the server will automatically generate a UUID and pass it in. | - -### Request example - -```shell -curl --location 'https://api.agora.io/ap/v1/projects/9d2498880e934632b38b0a68fa2f1622/rtls/ingress/streamkeys/:streamkey -' -``` + + + The UUID (Universally Unique Identifier) of the request. After passing in this field, the server will return this field in the response header. It is recommended to assign X-Request-ID a value. If no value is assigned, the Agora server will automatically generate a UUID and pass it in. + + + + + -### Response parameters +### Response **Headers** -| Header | Data type | Description | -| :------------- | :------- |:----------------------- | -| `X-Request-ID` | String | The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header.| + + + The UUID (Universally Unique Identifier) of the request. The value is in its `X-Request-ID` header. If a request error occurs, print the value in the log to troubleshoot the problem. A `401 (Unauthorized)` response status code means that there is no such field in the response header. + + **Response body** -For details about possible response status codes, see [Response status codes](../../response-status-codes). - -If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. - If the status code is `200`, the request succeeds, and the response body includes the following parameters: -| Parameter | Type | Description | -| :--------------- | :----- | :----------------------------------------------------------------- | -| `status` | String | The status of this request. `success` means the request succeeds. | -| `data` | Object | Includes the following fields:
  • `streamKey`: String, the queried streaming key.
  • `channel`: String. The name of the channel associated with the streaming key.
  • `uid`: String, the user UID in the channel associated with the streaming key.
  • `expiresAfter`: Integer, the validity period of the streaming key from the time of creation, in seconds.
  • `createdAt`: String, the Unix timestamp for when the streaming key was created, in seconds.
| -### Response example + + + The status of this request. `success` means the request succeeds. + + + Includes the following fields: + + The newly created streaming key. + + + The name of the channel associated with the streaming key. + + + The user UID in the channel associated with the streaming key. + + + Integer, the validity period of the streaming key from the time of creation, in seconds. + + + The Unix timestamp for when the streaming key was created, in seconds. + + + + +If the status code is not `200`, the request fails. See the `message` field in the response body for the reason for this failure. For details about possible response status codes, see [Response status codes](../../response-status-codes). -The following is a response example for a successful request: + + + +
+The endpoint requires [RESTful Authentication](/media-gateway/reference/restful-authentication#implement-basic-http-authentication). +
+
+ + + ```bash + curl --location 'https://api.agora.io/ap/v1/projects/9d2498880e934632b38b0a68fa2f1622/rtls/ingress/streamkeys/:streamkey + ' + ``` + + + ```js + fetch("https://api.agora.io/ap/v1/projects/9d2498880e934632b38b0a68fa2f1622/rtls/ingress/streamkeys/:streamkey", { + method: "GET", + headers: { + "Accept": "application/json", + "Authorization": "Basic " + } + }) + .then(response => response.json()) + .then(data => console.log(data)) + .catch(error => console.error("Error:", error)); + ``` + + + ```python + url = "https://api.agora.io/ap/v1/projects/9d2498880e934632b38b0a68fa2f1622/rtls/ingress/streamkeys/:streamkey" + + headers = { + "Accept": "application/json", + "Authorization": "Basic " + } + + response = requests.get(url, headers=headers) + ``` + + +
+
```json { "status" : "success" , @@ -73,5 +154,6 @@ The following is a response example for a successful request: } } ``` - - +
+ +