媒体同步 CLI 命令：SharePoint、Dropbox

媒体同步

媒体同步使媒体文件夹与 SharePoint、OneDrive for work、Dropbox 或 Google Drive 文件夹保持同步。每次运行都会导入来源文件夹内直接包含的图片（png、jpeg、webp、gif）、视频（mp4、webm）和音频（mp3）；子文件夹会被忽略。已更改的文件会在相同的媒体 ID 下替换其字节，因此播放它的每个播放列表都会更新；在来源处被删除或移出的文件会退出播放：其媒体会被删除，或者在仍有屏幕显示它时，移到 Removed 子文件夹，并在没有任何内容持有它时删除。其他文件会连同原因列为已跳过：请在播放列表中用文档链接显示 Office 文件或 PDF，并把 MOV 等格式导出为 MP4 H.264。播放列表通过 by:folder 选择器播放该文件夹。

每个同步都通过项目的一个账户读取。账户 ID 以 msa_ 开头，同步 ID 以 msy_ 开头。media sync account add microsoft365 保存您自己的 Microsoft Entra 应用，或指定项目的一个 Microsoft 连接；media sync account add dropbox 为 Dropbox 账户的所有者打印一次性链接；media sync account add google-drive 读取与服务账号地址（screenRIG 的或您自己的）共享的文件夹。先测试账户，再根据文件夹的地址创建同步：它立即到期。

用 --secret-file FILE 提供客户端密钥，用 --key-file FILE 提供 Google Drive 密钥，或用 - 从标准输入读取，绝不作为参数传入。密钥在服务器上加密封存，只会显示为 data.secret {set, hint}。读取需要 Read 访问权限，所有更改都需要 Manage 访问权限。

`media sync account add microsoft365`#

添加您自己的 Microsoft Entra 应用，或项目的 Microsoft 连接，以便同步可以读取 SharePoint 或 OneDrive for work 文件夹。

media sync account add microsoft365 --name NAME
    (--tenant-id TENANT --client-id ID --secret-file FILE | --connection-id ID)

参数	类型	必填	默认	备注
`--name NAME`	string	是	无	1 到 80 个字符。
`--tenant-id TENANT`	string	没有 `--connection-id`	无	您组织的目录（租户）ID，或其主域名，例如 `contoso.onmicrosoft.com`；绝不能是 `common`、`organizations` 或 `consumers`。需与 `--client-id` 和 `--secret-file` 一起使用。
`--client-id ID`	string	没有 `--connection-id`	无	应用注册的应用程序（客户端）ID，一个 GUID。
`--secret-file FILE`	string	没有 `--connection-id`	无	从此文件读取客户端密钥的值，或用 `-` 从标准输入读取（绝不作为参数传入）；文件中只包含该值。
`--connection-id ID`	string	没有 `--tenant-id`	无	通过项目的 Microsoft 连接（`pcn_…`）登录（两种模式均可），以代替 `--tenant-id`、`--client-id` 和 `--secret-file`。不能与它们一起使用。

screenrig media sync account add microsoft365 --name Contoso --tenant-id contoso.onmicrosoft.com --client-id 0b1d2f3a-4c5e-4f60-8a7b-9c0d1e2f3a4b --secret-file secret.txt
screenrig media sync account add microsoft365 --name Contoso --connection-id pcn_01EXAMPLECONNECTION0000

在 Microsoft Entra 管理中心注册一个不带重定向 URI 的单租户应用，添加客户端密钥（复制其值，而不是密钥 ID），添加 Microsoft Graph 应用程序权限 Sites.Selected（然后授予该应用对每个站点的读取权限）或 Files.Read.All，并授予管理员同意。该应用属于此项目。接着运行 media sync account test。

`media sync account add dropbox`#

添加 Dropbox 账户，并打印其所有者在登录 Dropbox 后打开以完成连接的一次性链接。

media sync account add dropbox --name NAME [--app-key KEY]

参数	类型	必填	默认	备注
`--name NAME`	string	是	无	1 到 80 个字符。
`--app-key KEY`	string	否	screenRIG 的 Dropbox 应用	您自己的 Dropbox 应用的 app key：1 到 64 个字母和数字，绝不是其 app secret。

screenrig media sync account add dropbox --name "Marketing Dropbox"
screenrig media sync account add dropbox --name "Marketing Dropbox" --app-key YOURAPPKEY

data.authorize_url 是链接，data.authorize_expires_at 是其到期时间。CLI 绝不会打开浏览器：请把链接发给 Dropbox 账户的所有者，由其允许只读访问（files.metadata.read、files.content.read、account_info.read、sharing.read）。运行 media sync account show，直到 data.state 变为 ready（初始为 pending_consent），然后运行 media sync create dropbox。您自己的 Dropbox 应用需要启用这些权限，并添加输出中打印的重定向 URI。

`media sync account add google-drive`#

添加 Google Drive 账户，立即可用，并打印用于共享文件夹的服务账号地址。

media sync account add google-drive --name NAME [--key-file FILE]

参数	类型	必填	默认	备注
`--name NAME`	string	是	无	1 到 80 个字符。
`--key-file FILE`	string	否	screenRIG 的服务账号	从此文件读取您自己的 Google Cloud 服务账号的 JSON 密钥，或用 `-` 从标准输入读取（绝不作为参数传入）。

screenrig media sync account add google-drive --name "Marketing Drive"
screenrig media sync account add google-drive --name "Marketing Drive" --key-file key.json

data.config.service_account_email 是要与每个文件夹共享的地址；Viewer 权限即可。通过 screenRIG 的服务账号，只有当此项目中邮箱已验证的成员共享或拥有该文件夹时，它才会同步（否则为 media_sync_sharer_not_member）。使用您自己的密钥时，任何与该服务账号共享的文件夹都会同步。

`media sync account list`#

列出此项目的媒体同步账户，并显示其类型、状态和最近一次测试；不会返回任何密钥。

media sync account list

无参数。

screenrig media sync account list

`media sync account show`#

查看一个账户：其租户和客户端 ID、状态、屏蔽后的密钥和最近一次测试。

media sync account show <id>

参数	类型	必填	默认	备注
`<id>`	string	是	无	账户（`msa_…`）。

screenrig media sync account show msa_01EXAMPLEACCOUNT0000000

Dropbox 账户还会显示是谁连接了它以及其 app_key；Google Drive 账户显示其 service_account_email。

`media sync account update`#

重命名账户，更改 Microsoft 应用的租户、应用程序 ID 或客户端密钥，或替换 Google Drive 账户自己的密钥。

media sync account update <id> [--name NAME] [--tenant-id TENANT] [--client-id ID]
    [--secret-file FILE | --key-file FILE] [--expect-rev REVISION]

参数	类型	必填	默认	备注
`<id>`	string	是	无	账户（`msa_…`）。
`--name NAME`	string	否	未更改	重命名账户。
`--tenant-id TENANT`	string	否	未更改	租户的目录 ID 或主域名。
`--client-id ID`	string	否	未更改	应用注册的应用程序（客户端）ID。
`--secret-file FILE`	string	否	未更改	从此文件读取新的客户端密钥的值，或用 `-` 从标准输入读取；它会替换已存储的密钥。省略的密钥会保留。
`--key-file FILE`	string	否	未更改	从此文件读取 Google Drive 账户自己的 JSON 密钥，或用 `-` 从标准输入读取；它必须属于同一个服务账号。不适用于 `--secret-file`。
`--expect-rev REVISION`	integer	否	无	除非账户处于此修订版本（`revision_conflict`，退出码 6），否则拒绝更改。

screenrig media sync account update msa_01EXAMPLEACCOUNT0000000 --secret-file new-secret.txt
screenrig media sync account update msa_01EXAMPLEACCOUNT0000000 --name "Contoso tenant" --expect-rev 2

至少需要一项更改。更改凭据会清除 last_test：请重新测试该账户。Entra 客户端密钥会过期，因此请在其过期之前在此替换密钥。

`media sync account connect`#

生成新的一次性链接，用于连接或重新连接 Dropbox 账户。

media sync account connect <id>

参数	类型	必填	默认	备注
`<id>`	string	是	无	账户（`msa_…`）。

screenrig media sync account connect msa_01EXAMPLEACCOUNT0000000

data.authorize_url 和 data.authorize_expires_at 带有该链接，它会取代之前的链接。把它发给 Dropbox 账户的所有者。当对方没有完成授权，或账户为 reconnect_required（Dropbox 不再认可该连接）时使用。已连接的账户在新的授权完成之前保持连接，而另一个 Dropbox 账户登录后会接管该连接。

`media sync account test`#

检查账户：Microsoft 应用的登录和 Graph 权限，或 Dropbox 或 Google Drive 账户的连接或密钥。

media sync account test <id>

参数	类型	必填	默认	备注
`<id>`	string	是	无	账户（`msa_…`）。

screenrig media sync account test msa_01EXAMPLEACCOUNT0000000

响应存储为 last_test。对于 Microsoft 应用，它报告 credentials（Microsoft 已签发令牌；被拒绝时会带有其 AADSTS 代码，例如密钥是 ID 而不是值时的 AADSTS7000215）和 permissions（令牌带有的 Graph 应用程序权限）。仅有 Sites.Selected 则为警告：每个站点仍然需要单独授予，共享链接则需要 Files.Read.All。该测试不判定站点的授权或某个文件夹：media sync create 会读取您指定的文件夹。检查失败时，data.ok 为 false，退出码为 0。

`media sync account delete`#

删除没有任何同步使用的账户。

media sync account delete <id> [--expect-rev REVISION]

参数	类型	必填	默认	备注
`<id>`	string	是	无	账户（`msa_…`）。
`--expect-rev REVISION`	integer	否	无	除非账户处于此修订版本（`revision_conflict`，退出码 6），否则拒绝删除。

screenrig media sync account delete msa_01EXAMPLEACCOUNT0000000

只要有同步使用该账户，响应就是 resource_conflict（退出码 5），并指明它们：请先删除这些同步。

`media sync create sharepoint`#

将 SharePoint 或 OneDrive for work 文件夹同步到媒体文件夹。

media sync create sharepoint --account-id ID --url URL [--folder-id ID] [--every DURATION] [--name NAME]

参数	类型	必填	默认	备注
`--account-id ID`	string	是	无	用于读取的账户（`msa_…`）。
`--url URL`	string	是	无	文件夹的 SharePoint 地址，例如 `https://contoso.sharepoint.com/sites/Marketing/Shared%20Documents/Lobby%20Signs`，在站点获得授权后可配合 `Sites.Selected` 使用；或其共享链接（Share、Copy link），这需要 `Files.Read.All`。个人 OneDrive（`onedrive.live.com`、`1drv.ms`）无法通过组织应用读取。
`--folder-id ID`	string	否	以来源文件夹命名的新媒体文件夹	文件所放入的媒体文件夹（`mfd_…`）。
`--every DURATION`	string	否	`15m`	检查变更的频率，5 分钟到 24 小时：`15m`、`1h`、`6h`，或纯秒数（300 到 86400）。
`--name NAME`	string	否	来源文件夹的名称	1 到 80 个字符。

screenrig media sync create sharepoint --account-id msa_01EXAMPLEACCOUNT0000000 --url https://contoso.sharepoint.com/sites/Marketing/Shared%20Documents/Lobby%20Signs
screenrig media sync create sharepoint --account-id msa_01EXAMPLEACCOUNT0000000 --url "https://contoso.sharepoint.com/:f:/s/Marketing/EabcDEF" --folder-id mfd_01EXAMPLEFOLDER000000000 --every 1h --name "Lobby signs"

Microsoft 拒绝的文件夹会返回 media_sync_source_refused（退出码 5），并附带需要授予的权限；不会存储任何内容。

`media sync create dropbox`#

将 Dropbox 文件夹同步到媒体文件夹。

media sync create dropbox --account-id ID --url URL|PATH [--folder-id ID] [--every DURATION] [--name NAME]

参数	类型	必填	默认	备注
`--account-id ID`	string	是	无	用于读取的已连接 Dropbox 账户（`msa_…`）。
`--url URL`	string	是	无	文件夹的 Dropbox 地址（`https://www.dropbox.com/home/...`）、账户已添加到其 Dropbox 的共享文件夹链接，或以 `/` 开头的路径。团队空间中的文件夹从团队根目录读取。
`--folder-id ID`	string	否	以来源文件夹命名的新媒体文件夹	文件所放入的媒体文件夹（`mfd_…`）。
`--every DURATION`	string	否	`15m`	检查变更的频率，5 分钟到 24 小时：`15m`、`1h`、`6h`，或纯秒数（300 到 86400）。
`--name NAME`	string	否	来源文件夹的名称	1 到 80 个字符。

screenrig media sync create dropbox --account-id msa_01EXAMPLEACCOUNT0000000 --url https://www.dropbox.com/home/Marketing/Lobby%20Signs
screenrig media sync create dropbox --account-id msa_01EXAMPLEACCOUNT0000000 --url /Marketing/Lobby --folder-id mfd_01EXAMPLEFOLDER000000000 --every 1h --name "Lobby signs"

每次运行都从 Dropbox 在该文件夹中保存的位置继续，只读取发生变化的内容。账户无法打开的文件夹为 media_sync_source_refused，Dropbox 不再认可的连接为 dropbox_reconnect_required（media sync account connect）：两者的退出码均为 5，不存储任何内容。

`media sync create google-drive`#

将与账户的服务账号共享的 Google Drive 文件夹同步到媒体文件夹。

media sync create google-drive --account-id ID --url URL|ID [--folder-id ID] [--every DURATION] [--name NAME]

参数	类型	必填	默认	备注
`--account-id ID`	string	是	无	用于读取的 Google Drive 账户（`msa_…`）。
`--url URL`	string	是	无	文件夹的地址（`https://drive.google.com/drive/folders/ID`）或其 ID。请先把文件夹共享给账户的 `service_account_email`；Viewer 权限即可。
`--folder-id ID`	string	否	以来源文件夹命名的新媒体文件夹	文件所放入的媒体文件夹（`mfd_…`）。
`--every DURATION`	string	否	`15m`	检查变更的频率，5 分钟到 24 小时：`15m`、`1h`、`6h`，或纯秒数（300 到 86400）。
`--name NAME`	string	否	来源文件夹的名称	1 到 80 个字符。

screenrig media sync create google-drive --account-id msa_01EXAMPLEACCOUNT0000000 --url https://drive.google.com/drive/folders/1AbCdEfGhIjKlMnOpQrStUvWxYz --folder-id mfd_01EXAMPLEFOLDER000000000 --every 1h
screenrig media sync create google-drive --account-id msa_01EXAMPLEACCOUNT0000000 --url 1AbCdEfGhIjKlMnOpQrStUvWxYz

通过 screenRIG 的服务账号，只有当此项目中邮箱已验证的成员共享或拥有该文件夹时，它才会同步（media_sync_sharer_not_member，退出码 3，不存储任何内容）。每次运行都会重新检查这一点，失去这样的共享者的文件夹会使同步停在 error 状态，并保留其媒体：请从成员的 Google 账号重新共享，然后运行 media sync update ID --resume。Google Docs、Sheets 和 Slides 文件会作为 unsupported_type 被跳过。地址无法打开的文件夹为 media_sync_source_refused（退出码 5）：请将其共享给该服务账号。

`media sync list`#

列出此项目的媒体同步，并显示其媒体文件夹、频率、状态和最近一次运行的状态。

media sync list

无参数。

screenrig media sync list

`media sync show`#

查看一个同步及其最近一次运行的摘要。

media sync show <id>

参数	类型	必填	默认	备注
`<id>`	string	是	无	同步（`msy_…`）。

screenrig media sync show msy_01EXAMPLESYNC000000000

data.last_run 带有 status（ok、partial 或 error）、added、updated、removed、pending_delete（屏幕仍持有的已移除文件，在 Removed 文件夹中等待）、skipped_total 以及 skipped（前 20 个被跳过的文件，附每个文件的原因：unsupported_type, too_large, storage, subfolder, download_failed, unreadable, in_use）；失败的运行带有 error，其中的 code 和 detail 会指明修复方法。data.source 为 Dropbox 增加 path，为 Google Drive 增加 shared_by。

状态为 error 的同步需要修复。其媒体文件夹已被删除：用 media sync update --folder-id 将其指向另一个文件夹。其来源文件夹已被删除或移动：删除该同步并创建一个新的。对于通过 screenRIG 服务账号使用的 Google Drive，该文件夹失去了已验证的共享者（sharer_not_member）：请从项目成员的 Google 账号重新共享，然后运行 media sync update ID --resume。当 Dropbox 不再认可该连接（media sync account connect）时，Dropbox 运行会以 reconnect_required 失败。

`media sync update`#

更改同步的名称、频率或媒体文件夹，或暂停和恢复它。

media sync update <id> [--name NAME] [--every DURATION] [--folder-id ID]
    [--pause | --resume] [--expect-rev REVISION]

参数	类型	必填	默认	备注
`<id>`	string	是	无	同步（`msy_…`）。
`--name NAME`	string	否	未更改	重命名同步。
`--every DURATION`	string	否	未更改	检查变更的频率，5 分钟到 24 小时。
`--folder-id ID`	string	否	未更改	改为填充此媒体文件夹（`mfd_…`）。下一次运行会重新读取整个来源，并把每个已同步的文件放入其中。
`--pause`	boolean	否	关闭	停止运行，直到恢复。不适用于 `--resume`。
`--resume`	boolean	否	关闭	恢复运行；也会重新启动因错误而停止的同步。不适用于 `--pause`。
`--expect-rev REVISION`	integer	否	无	除非同步处于此修订版本（`revision_conflict`，退出码 6），否则拒绝更改。

screenrig media sync update msy_01EXAMPLESYNC000000000 --every 1h
screenrig media sync update msy_01EXAMPLESYNC000000000 --pause
screenrig media sync update msy_01EXAMPLESYNC000000000 --folder-id mfd_01EXAMPLEFOLDER000000000 --expect-rev 3

至少需要一项更改。

`media sync run`#

立即运行同步，而不是等到下一次运行时间。

media sync run <id>

参数	类型	必填	默认	备注
`<id>`	string	是	无	同步（`msy_…`）。

screenrig media sync run msy_01EXAMPLESYNC000000000

同步会在大约 30 秒内运行，之后 media sync show 会显示其最近一次运行。已暂停的同步必须先恢复。

`media sync delete`#

停止同步；其媒体和文件夹会保留。

media sync delete <id> [--expect-rev REVISION]

参数	类型	必填	默认	备注
`<id>`	string	是	无	同步（`msy_…`）。
`--expect-rev REVISION`	integer	否	无	除非同步处于此修订版本（`revision_conflict`，退出码 6），否则拒绝删除。

screenrig media sync delete msy_01EXAMPLESYNC000000000

同步会忘记哪个来源文件对应哪个媒体。已导入的媒体和媒体文件夹会保留，不会移除任何内容。

媒体同步

media sync account add microsoft365#

media sync account add dropbox#

media sync account add google-drive#

media sync account list#

media sync account show#

media sync account update#

media sync account connect#

media sync account test#

media sync account delete#

media sync create sharepoint#

media sync create dropbox#

media sync create google-drive#

media sync list#

media sync show#

media sync update#

media sync run#

media sync delete#

其他命令组