Mopidy HTTP JSON-RPC API 完整指南：通过 HTTP POST 与 WebSocket 调用 Core API 并订阅事件

音视频后端【免费下载链接】mopidyMopidy is an extensible music server written in Python项目地址https://gitcode.com/gh_mirrors/mo/mopidy点击查看免费下载Mopidy 是可扩展的 Python 音乐服务器其 HTTP 扩展mopidy.http将完整的 Core API 以 JSON-RPC 2.0 协议暴露出来供外部客户端通过 HTTP POST 和 WebSocket 两种方式远程调用。本文基于 docs/api/http.rst 文档结合仓库源码与测试用例系统讲解请求/响应消息格式、两种传输通道的使用方法、事件推送机制以及底层实现原理读完即可用 curl 或 JavaScript 客户端驱动 Mopidy 播放、查询与控制音乐库。概览HTTP 扩展如何暴露 Core APIMopidy 的架构是「前端frontend— 核心core— 后端backend」三层模型。HTTP 扩展Mopidy-HTTP是一个前端实现它由 src/mopidy/http/actor.py 中的HttpFrontend负责启动内嵌的 Tornado Web 服务器把 docs/api/core.rst 中定义的核心 APIcore.playback、core.tracklist、core.library、core.playlists、core.mixer、core.history等控制器以及core.get_version、core.get_uri_schemes包装为 JSON-RPC 2.0 方法对外提供。它提供两种访问通道通道端点特点HTTP POST APIhttp://localhost:6680/mopidy/rpc请求/响应模式可调用完整 Core API但不会推送事件WebSocket APIhttp://localhost:6680/mopidy/ws可调用完整 Core API并且 Mopidy 会实时向客户端推送事件其中localhost:6680部分随你的实际配置而变化见下文 配置小节。另外官方还提供 JavaScript 包装库 Mopidy.js将 WebSocket JSON-RPC API 封装成友好的 JavaScript API适用于浏览器与 Node.jsMopidy-API-Explorer 扩展则可用于熟悉这些基于 HTTP 的 API。本文以当前仓库源码为准。HTTP 扩展的默认配置位于 src/mopidy/http/ext.conf配置模式schema定义在 src/mopidy/http/init.py。通道一HTTP POST APIMopidy 的 Web 服务器接受发送到http://localhost:6680/mopidy/rpc的 HTTP POST 请求。请求必须设置Content-Type: application/json头。HTTP POST 端点可以访问 Mopidy 的全部 Core API但不会向客户端推送事件通知如果你需要监听事件应该使用 WebSocket API。命令行示例从命令行使用 curl 发起一次调用$ curl -d {jsonrpc: 2.0, id: 1, method: core.playback.get_state} -H Content-Type: application/json http://localhost:6680/mopidy/rpc {jsonrpc: 2.0, id: 1, result: stopped}服务端处理细节从源码看/mopidy/rpc由 src/mopidy/http/handlers.py 中的JsonRpcHandler处理其行为要点如下Content-Type 强制校验当启用 CSRF 防护时默认开启POST处理器会先解析请求头中的Content-Type如果不是application/json直接返回 HTTP415 Unsupported Media Type原因是Content-Type must be application/json见 handlers.py。测试用例test_post_wrong_content_type_unsupported验证了这一行为tests/http/test_handlers.py。响应头所有 RPC 响应都会附带Cache-Control: no-cache、X-Mopidy-Version: 版本号、Accept: application/json、Content-Type: application/json; utf-8等头见 handlers.py。CORS 支持当请求携带Origin头即来自浏览器的跨域请求且通过了预检OPTIONS时服务端会返回Access-Control-Allow-Origin与Access-Control-Allow-Headers: Content-Type见 handlers.py。调用链从 HTTP 到 Core Actor每个 HTTP 请求最终都会进入 JSON-RPC 包装器。在 handlers.py 的make_jsonrpc_wrapper中Core 的各个控制器被挂载到core.*命名空间下core.describe—— 返回描述全部可用方法的数据结构core.get_uri_schemes、core.get_versioncore.history、core.library、core.mixer、core.playback、core.playlists、core.tracklist包装器会使用models.ModelJSONEncoder/models.model_json_decoder对返回的模型对象如Track、Artist、Album进行序列化/反序列化见 src/mopidy/internal/jsonrpc.py。由于 Core 是 Pykka ActorWrapper._unwrap_result会在返回前等待并取出pykka.Future的结果见 jsonrpc.py因此客户端拿到的是最终结果而非异步句柄。通道二WebSocket APIMopidy 的 Web 服务器在http://localhost:6680/mopidy/ws暴露一个 WebSocket 端点。WebSocket 提供对 Mopidy 完整 API 的访问并且能让 Mopidy 在事件发生时立即将事件推送给客户端。双向消息模型在 WebSocket 上存在两种消息客户端 → 服务端JSON-RPC 2.0 请求服务端以 JSON-RPC 2.0 响应回复服务端 → 客户端当 Mopidy 内部发生事件时推送的事件消息见下一节「事件消息」。两种消息都以 JSON 对象编码。服务端处理细节/mopidy/ws由 src/mopidy/http/handlers.py 中的WebSocketHandler处理每个连接建立后会被加入类级集合clients关闭时移除见 handlers.py。收到的每条消息通过同一个jsonrpc.Wrapper.handle_json处理见 handlers.py与 HTTP POST 共用同一套 JSON-RPC 实现只是传输层不同。事件广播通过WebSocketHandler.broadcast静态方法完成它会遍历所有存活客户端通过io_loop.add_callback安全地跨线程投递消息见 handlers.py。测试用例test_broadcast_makes_it_to_client、test_broadcast_to_client_that_just_closed_connection验证了广播路径tests/http/test_handlers.py。从浏览器 / Node.js 使用如果你在浏览器或 Node.js 中使用 JavaScript 调用该 API应优先使用 Mopidy.js——它把 WebSocket API 包装为简洁的 JavaScript APInew Mopidy({webSocketUrl: ws://localhost:6680/mopidy/ws})之类免去手动组装 JSON-RPC 消息的繁琐。JSON-RPC 2.0 消息格式JSON-RPC 2.0 消息可以通过检查是否存在键名为jsonrpc、值为字符串2.0的字段来识别。消息格式细节请参阅 JSON-RPC 2.0 规范。方法命名映射Core API 中的所有方法都可以通过 JSON-RPC 调用。命名规则为控制器挂载点 . 方法名。例如mopidy.core.PlaybackController.play对应 JSON-RPC 方法core.playback.play。请求示例{jsonrpc: 2.0, id: 1, method: core.playback.get_current_track}响应示例{jsonrpc: 2.0, id: 1, result: {__model__: Track, ...: ...}}注意响应中的result带有__model__标记字段这是 Mopidy 模型对象的序列化标记由models.ModelJSONEncoder输出用于在解码时还原为对应的模型类型。使用 core.describe 探索 APIJSON-RPC 方法core.describe返回一个描述所有可用方法的数据结构。如果你不确定 Core API 如何映射到 JSON-RPC查看core.describe的响应会很有帮助。该方法的实现基于 src/mopidy/internal/jsonrpc.py 中的Inspector它通过 Pythoninspect模块枚举挂载对象的所有公共方法跳过下划线开头的私有方法并提取每个方法的文档字符串与参数签名包括参数名、默认值、*args/**kwargs标记最终组装成{方法名: {description, params}}形式的描述结构。参数传递请求支持两种参数形式见 jsonrpc.py 的_get_params按位置传递params: [...]数组按名称传递params: {...}对象两者最终都会映射为被调用 Python 方法的*args, **kwargs。若省略params字段则视为无参数调用。通知Notification与批处理从 src/mopidy/internal/jsonrpc.py 的实现可以补充两点协议细节通知请求中若省略id或id为null则视为通知——服务端不返回响应见_handle_single_request中的判断。批处理请求可以是一个 JSON 数组一次发送多个请求服务端按顺序处理并返回对应的响应数组空数组会返回Invalid Request错误。错误响应结构当调用出错时响应会形如{ jsonrpc: 2.0, id: 1, error: {code: -32601, message: Method not found, data: {...}} }服务端定义的错误码见 jsonrpc.py错误类codemessageParseError-32700Parse errorInvalidRequestError-32600Invalid RequestMethodNotFoundError-32601Method not foundInvalidParamsError-32602Invalid paramsApplicationError0Application errorJsonRpcError基类-32000Unspecified server error其中InvalidParamsError与ApplicationError会在data中附带异常类型、异常消息与 traceback方便排查。另外服务端会拒绝调用下划线开头的私有方法并返回Method not found见 jsonrpc.py。事件消息事件对象总是包含一个键名为event的字段其值为事件类型。根据事件类型的不同事件对象可能包含与事件相关的额外数据字段。事件与 CoreListener 的映射事件直接映射到mopidy.core.CoreListenerAPI见 docs/api/core.rst 与 src/mopidy/core/listener.pyCoreListener的方法名即可用的事件类型而CoreListener方法的关键字参数会全部作为事件对象的额外字段包含在内。例如事件消息{event: track_playback_started, track: {...}}对应CoreListener.track_playback_started(track)这一回调event字段是方法名track字段是方法的track关键字参数值为序列化后的 Track 模型。事件如何被推送在服务端HttpFrontend本身实现了CoreListener见 actor.py当 Core 层发生任何事件时Pykka 会调用HttpFrontend.on_event该方法将事件名写入数据后由models.ModelJSONEncoder序列化再交给WebSocketHandler.broadcast推送给所有已连接的 WebSocket 客户端见 actor.py。常见事件类型从 src/mopidy/core/listener.py 的源码结构看典型事件包括均为CoreListener的公开方法名播放控制类playback_state_changed、track_playback_started、track_playback_paused、track_playback_resumed、track_playback_ended、stream_title_changed队列类tracklist_changed播放列表类playlists_changed媒体库类library_changed音量类volume_changed选项类options_changed连接/查找类seeked、playback_error配置与安全选项HTTP 扩展的完整配置项定义在 src/mopidy/http/ext.conf 与 src/mopidy/http/init.py 中配置项默认值说明enabledtrue是否启用 HTTP 扩展hostname127.0.0.1监听地址可设为0.0.0.0或::IPv6 全监听以允许局域网访问port6680监听端口zeroconfMopidy HTTP server on $hostname通过零配置网络mDNS/DNS-SD广播服务类型为_http._tcp与_mopidy-http._tcp见 actor.pyallowed_origins空允许跨域访问的 Origin 列表逗号分隔自动转小写、去重csrf_protectiontrue是否启用跨站请求伪造防护default_appmopidy访问/时重定向到的默认 Web 应用安全机制CSRF 防护启用时默认浏览器发起的请求必须先通过 Origin 校验。服务端通过「强制application/jsonContent-Type OPTIONS 预检」的组合限制浏览器 CSRF 场景见 [handlers.py](https://link.gitcode.com/i/d2db9e9d0b846994c858ef8c54da9974, L281-L292)非浏览器的 HTTP 客户端只需设置正确的 Content-Type 即可正常调用不受影响。Origin 校验check_origin见 handlers.py会拒绝缺失 Origin 头或 Origin 与Host头、allowed_origins列表均不匹配的请求file://、null这类本地文件 Origin 会被放行以兼容 Apache Cordova 等本地打包客户端。测试用例CheckOriginTests全面覆盖了这些分支tests/http/test_handlers.py。Cookie 密钥Tornado 应用使用随机生成的cookie_secret写入 HTTP 扩展数据目录下的cookie_secret文件见 actor.py。扩展性为 HTTP 服务器挂载自己的应用HTTP 服务器不仅服务 Mopidy 自身 API还开放给其他扩展通过扩展注册表http:static键注册静态文件目录、通过http:app键注册 Tornado 应用或 WSGI 应用详见 docs/api/http-server.rst。所有已注册应用会被收集到HttpFrontend.apps/HttpFrontend.statics路由前缀为该应用的name见 actor.py。参考链接本主题文档docs/api/http.rstHTTP 服务器端扩展 APIdocs/api/http-server.rstCore API 定义docs/api/core.rstHTTP 前端实现src/mopidy/http/actor.py请求处理器JsonRpcHandler/WebSocketHandlersrc/mopidy/http/handlers.pyJSON-RPC 2.0 包装器与 Inspectorsrc/mopidy/internal/jsonrpc.pyHTTP 扩展配置模式与默认配置src/mopidy/http/init.py、src/mopidy/http/ext.conf处理器测试用例tests/http/test_handlers.py赞分享音视频后端【免费下载链接】mopidyMopidy is an extensible music server written in Python项目地址https://gitcode.com/gh_mirrors/mo/mopidy点击查看免费下载相关推荐ntfy 订阅 API 完整指南HTTP 流JSON/SSE/Raw与 WebSocket 实时订阅ntfy 订阅 API 完整指南HTTP 流JSON/SSE/Raw与 WebSocket 实时订阅 本篇技术指南围绕 ntfy 开源项目 PUT/PO后端即时通讯消息队列Prisma Subscriptions 实时订阅 API 完整指南WebSocket 协议、类型订阅与过滤机制Prisma Subscriptions 实时订阅 API 完整指南WebSocket 协议、类型订阅与过滤机制 导读 在 Prisma 服务中GraphQ后端数据库GraphQLSeaTunnel GraphQL Source Connector 完整指南HTTP 查询、WebSocket 订阅与 Schema 解析SeaTunnel GraphQL Source Connector 完整指南HTTP 查询、WebSocket 订阅与 Schema 解析 本文基于 Gra数据集成ETL大数据批处理流处理变更数据捕获上一篇Jellium Desktop媒体库基础教程从零开始打造你的专属媒体中心下一篇CVAT终极部署指南零基础快速搭建计算机视觉标注平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考