跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

GraphQL 分析 API

最后更新 查看 MarkdownAgent 设置

Stream 通过下方描述的 GraphQL API 以及 Cloudflare 仪表板的 Stream Analytics 页面提供直播视频和上传到 Stream 的视频的分析数据。

前往 Analytics(分析) ↗

Stream Analytics API 使用 Cloudflare GraphQL Analytics API,可用于许多 Cloudflare 产品。有关 GraphQL、速率限制、过滤和排序的更多信息,请参阅 Cloudflare GraphQL Analytics API 文档。

快速入门

  1. 在 Cloudflare 仪表板中,前往 Account API tokens(账户 API 令牌) 页面。

    前往 Account API tokens(账户 API 令牌) ↗
  2. 生成具有 Account Analytics 权限的 API token。

  3. 使用您选择的 GraphQL 客户端发送第一个查询。Postman ↗ 内置 GraphQL 客户端,可帮助您运行第一个查询并 introspect GraphQL schema 以了解可用功能。

以下各节介绍多个数据集中的可用指标、维度、字段和查询示例。

在 viewer.accounts 下查询 Stream 数据集。使用 filter 选择记录,并使用 dimensions 对结果分组。

分组数据集会公开 avg、sum 和 count 等聚合值。原始数据集会直接返回字段,不包含聚合对象。

带点号的字段路径表示嵌套选择:sum.minutesViewed 表示 sum { minutesViewed }。

如需查看当前字段和筛选运算符,请使用自省功能探索 GraphQL 架构。以下摘要说明了有用的字段。

通过 HLS/DASH 和 WebRTC 交付的视频

Stream 会统计直播和点播视频的交付分钟数。这些数据包括通过 HLS/DASH 和 WebRTC(WHEP)交付的视频分钟数,与播放器无关。这是计费指标,但 GraphQL 数据经过抽样,因此可能与发票中报告的计费使用量不完全一致。

使用 streamMinutesViewedAdaptiveGroups 查询这些交付指标。

筛选条件和维度

此数据集支持以下筛选条件和分组维度:

字段 描述
date 日期
datetime 日期和时间
uid 视频 ID(适用于 HLS/DASH)或输入 ID(适用于 WebRTC/WHEP)
clientCountryName 观看者的 ISO 3166-1 alpha-2 国家/地区代码
creator 与视频关联的创建者 ID(如果已设置)

某些过滤器(如 date)可与 gt(大于)和 lt(小于)等运算符配合使用,如下面的示例查询所示。有关更多高级过滤选项,请参阅 过滤。

指标

此数据集公开以下指标:

字段 描述
count 每个维度组的值数量
sum.minutesViewed 交付的视频分钟数(必须以总和形式查询)

示例

按国家/地区获取观看分钟数

GraphQL requestgraphql
query StreamGetMinutesExample($accountTag: string!, $start: Date, $end: Date) {
    viewer {
        accounts(filter: { accountTag: $accountTag }) {
            streamMinutesViewedAdaptiveGroups(
                filter: { date_geq: $start, date_lt: $end }
                orderBy: [sum_minutesViewed_DESC]
                limit: 100
            ) {
                sum {
                    minutesViewed
                }
                dimensions {
                    uid
                    clientCountryName
                }
            }
        }
    }
}
GraphQL responsejson
{
    "data": {
        "viewer": {
            "accounts": [
                {
                    "streamMinutesViewedAdaptiveGroups": [
                        {
                            "dimensions": {
                                "clientCountryName": "US",
                                "uid": "<VIDEO_ID>"
                            },
                            "sum": {
                                "minutesViewed": 2234
                            }
                        },
                        {
                            "dimensions": {
                                "clientCountryName": "CN",
                                "uid": "<VIDEO_ID>"
                            },
                            "sum": {
                                "minutesViewed": 700
                            }
                        },
                        {
                            "dimensions": {
                                "clientCountryName": "IN",
                                "uid": "<VIDEO_ID>"
                            },
                            "sum": {
                                "minutesViewed": 553
                            }
                        }
                    ]
                }
            ]
        }
    },
    "errors": null
}

RTMP 和 SRT 输入指标

使用这些数据集检查 RTMP 或 SRT 输入。查询 liveInputEventsAdaptive 可获取事件,查询 liveInputEventsAdaptiveGroups 可获取已存储的视频片段指标。这些数据集经过抽样,因此可考虑使用 Webhook 或 Workers 事件订阅实时接收事件。

事件字段

liveInputEventsAdaptive 会直接返回事件日志字段,而非视频片段指标。它会排除 eventDescription 为空的事件。

你可以选择和筛选以下字段:

字段 描述
datetime 事件日期和时间
inputId 实时输入 ID
coloCode 摄取数据中心代码
eventCode 事件代码
eventDescription 事件说明

筛选条件和维度

liveInputEventsAdaptiveGroups 仅包含已存储视频片段的事件。它支持以下筛选条件和分组维度:

字段 描述
date 日期
datetime 日期和时间
eventCode 已存储视频片段的事件代码
inputId 实时输入 ID

指标

GOP(图像组)是一系列视频帧。“GOP 大小”有时也称为“关键帧间隔”。这些指标都与每个 GOP 的视频片段有关:

字段 描述
count 已存储的视频片段数量
avg.gopUploadTime, min.gopUploadTime, max.gopUploadTime GOP 上传时间,单位为毫秒
avg.gopDuration, min.gopDuration, max.gopDuration GOP 时长,单位为毫秒
avg.gopByteSize, min.gopByteSize, max.gopByteSize GOP 大小,单位为字节

如需估算平均广播比特率,请按 inputId 和广播的 datetime 范围筛选 liveInputEventsAdaptiveGroups。在同一分组中选择 avg.gopByteSize 和 avg.gopDuration。

省略 dimensions 可获取整个广播的单个结果。例如,使用以字节为单位的 avg.gopByteSize 和以毫秒为单位的 avg.gopDuration 计算每秒比特数:

Average broadcast bitratetxt
bitrate_bps = 8000 * avg.gopByteSize / avg.gopDuration

两个平均值使用相同的抽样权重,因此两者的比值可用于估算总字节数除以总媒体时长。只有当 avg.gopDuration 大于零时才计算该比值。

HLS/DASH 体验质量指标

通用媒体客户端数据(CMCD)会报告客户端播放测量数据。Stream 内置播放器和受支持的自定义播放器会提供 CMCD。

使用 streamCMCDAdaptiveGroups 查询体验质量(QoE)指标。这些测量数据描述播放器体验,不代表可计费的交付分钟数。

筛选条件和维度

此数据集支持以下筛选条件和分组维度:

字段 描述
videoId 视频 ID
creatorId 创建者 ID
inputId 实时输入 ID
sessionId CMCD 会话 ID
contentId 内容 ID
country ISO 3166-1 alpha-3 国家/地区代码,与交付指标使用的 alpha-2 代码不同
resolution 视频分辨率
bufferStarvation 如果上一次和当前请求之间发生缓冲停滞,则为 1;否则为 0
bufferStarvationDuration 缓冲停滞时长,单位为毫秒
initialBufferStarvationDuration 初始缓冲停滞时长,单位为毫秒
bufferLength 所请求对象的缓冲长度
measuredThroughput 客户端与服务器之间的测量吞吐量
streamType 直播为 l,点播视频为 v
encodedBitrate 所请求对象的编码比特率
objectDuration 所请求对象的时长,单位为毫秒
startup 如果所请求对象为启动所需,则为 1;否则为 0
streamingFormat HLS 或低延迟 HLS(LL-HLS)为 h,DASH 为 d
hlsType HLS 或 LL-HLS 为 hls 或 ll-hls,否则为空
topBitrate 最高比特率的转码版本
playbackRate 播放速率:实时播放为 1,两倍速为 2,未播放时为 0
date 日期
datetime 日期和时间

指标

此数据集公开以下聚合值:

字段 描述
count 每个维度组的值数量
sum.millisecondsViewed 根据成功请求估算的观看时长,单位为毫秒
uniq.viewers 仅统计成功请求中的唯一 CMCD 会话 ID,不代表唯一人数
avg.bufferStarvationDuration 平均缓冲停滞时长,单位为毫秒
avg.initialBufferStarvationDuration 平均初始缓冲停滞时长,单位为毫秒
avg.bufferLength 平均缓冲长度
avg.encodedBitrate 平均编码比特率
avg.measuredThroughput 平均测量吞吐量
max.latestDatetime 最后一次看到该维度组合的时间

在 quantiles 下选择百分位字段。所有时长的单位均为毫秒;P999 表示第 99.9 百分位:

字段 描述
bufferStarvationDurationP25 缓冲停滞时长的第 25 百分位
bufferStarvationDurationP50 缓冲停滞时长的第 50 百分位
bufferStarvationDurationP75 缓冲停滞时长的第 75 百分位
bufferStarvationDurationP90 缓冲停滞时长的第 90 百分位
bufferStarvationDurationP95 缓冲停滞时长的第 95 百分位
bufferStarvationDurationP99 缓冲停滞时长的第 99 百分位
bufferStarvationDurationP999 缓冲停滞时长的第 99.9 百分位
initialBufferStarvationDurationP25 初始缓冲停滞时长的第 25 百分位
initialBufferStarvationDurationP50 初始缓冲停滞时长的第 50 百分位
initialBufferStarvationDurationP75 初始缓冲停滞时长的第 75 百分位
initialBufferStarvationDurationP90 初始缓冲停滞时长的第 90 百分位
initialBufferStarvationDurationP95 初始缓冲停滞时长的第 95 百分位
initialBufferStarvationDurationP99 初始缓冲停滞时长的第 99 百分位
initialBufferStarvationDurationP999 初始缓冲停滞时长的第 99.9 百分位

WebRTC WHIP/WHEP 指标

使用 streamWHIPBroadcastMetricsAdaptive 和 streamWHIPBroadcastMetricsAdaptiveGroups 检查 WebRTC-HTTP 摄取协议(WHIP)输入。如需查看 WebRTC-HTTP 输出协议(WHEP)的播放数据,请查询交付分钟数。

Stream 每 15 秒收集一次 WHIP 观测数据。这些数据可能需要 2 到 3 分钟才能供查询。

原始字段

streamWHIPBroadcastMetricsAdaptive 会直接返回以下字段。你也可以在筛选条件中使用这些字段:

字段 描述
sampleInterval 自适应抽样间隔,而非观测时长
datetime 观测日期和时间
inputId 实时输入 ID
peerConnectionState 对等连接状态
iceConnectionState 交互式连接建立(ICE)连接状态
trackIngestState 轨道输入状态
codecName 编解码器名称
codecMimeType 编解码器媒体类型
peerConnectionId 对等连接 ID
trackId 轨道 ID
mediaKind audio 或 video
receivedBytes 观测期间接收的字节数
receivedPackets 观察期间接收的实时传输协议(RTP)数据包
droppedPackets 观察期间从摄取缓冲区丢弃的 RTP 数据包,并非全部网络丢包
observationDurationSeconds 观察时长(秒)

筛选条件和维度

streamWHIPBroadcastMetricsAdaptiveGroups 支持以下筛选器和分组维度:

字段 描述
date 日期
datetime 日期和时间
sampleInterval 自适应采样间隔
inputId 实时输入 ID
peerConnectionState 对等连接状态
iceConnectionState ICE 连接状态
trackIngestState 轨道输入状态
codecName 编解码器名称
codecMimeType 编解码器媒体类型
peerConnectionId 对等连接 ID
trackId 轨道 ID
mediaKind audio 或 video

指标

分组数据集公开以下指标。直接选择 count,并选择 sum 或 avg 下的嵌套字段:

字段 描述
count 估算的观察次数
sum.receivedBytes 估算的接收字节总数
sum.receivedPackets 估算的接收 RTP 数据包总数
sum.droppedPackets 估算的从摄取缓冲区丢弃的 RTP 数据包总数
sum.observationDurationSeconds 估算的观察总时长(秒)
avg.sampleInterval 平均自适应采样间隔
avg.ingestBitrate 接收的 bit 数除以观察秒数,单位为 bit/s
avg.ingestPacketRate 摄取数据包速率,单位为数据包/秒

分页

GraphQL API 支持 seek 分页:使用过滤器,您可以指定最后一个 video UID,使响应仅包含该 video UID 之后的视频数据。

查询返回 $uId 之后的两个视频的数据。将 $uId 设置为上一个响应中最后一个视频的 UID:

GraphQL querygraphql
query StreamPaginationExample(
    $accountTag: string!
    $start: Date
    $end: Date
    $uId: string
) {
    viewer {
        accounts(filter: { accountTag: $accountTag }) {
            streamMinutesViewedAdaptiveGroups(
                filter: { date_geq: $start, date_lt: $end, uid_gt: $uId }
                orderBy: [uid_ASC]
                limit: 2
            ) {
                count
                sum {
                    minutesViewed
                }
                dimensions {
                    uid
                }
            }
        }
    }
}

实现分页的步骤:

  1. 调用第一个查询(不带 uid_gt 过滤器)以获取第一组视频
  2. 从第一个查询的响应中获取最后一个 video UID
  3. 调用下一个查询,指定 uid_gt 属性并将其设为最后一个 video UID。这将返回下一组视频

有关分页的更多信息,请参阅 Cloudflare GraphQL Analytics API 文档。

限制

查询间隔和保留期限具有数据集特定的默认值:

数据集 最大查询间隔 数据保留期限
streamMinutesViewedAdaptiveGroups 32 天(768 小时) 92 天(2,208 小时)
liveInputEventsAdaptive 30 天 31 天
liveInputEventsAdaptiveGroups 30 天 31 天
streamCMCDAdaptiveGroups 30 天 31 天
streamWHIPBroadcastMetricsAdaptive 30 天 30 天
streamWHIPBroadcastMetricsAdaptiveGroups 30 天 30 天

使用 viewer.accounts 下的设置节点检查账户的限制。maxDuration 和 notOlderThan 字段以秒为单位报告查询间隔和保留期限。

这篇文档对您有帮助吗?