创建适用于 Android 的云媒体提供程序

云媒体提供商向 Android 照片选择器提供其他云媒体内容。当应用使用 ACTION_PICK_IMAGES 或 ACTION_GET_CONTENT 向用户请求媒体文件时，用户可以选择云媒体提供程序提供的照片或视频。云媒体提供商还可以提供有关影集的信息，您可以在 Android 照片选择器中浏览这些信息。

准备工作

在开始构建云媒体提供方之前，请考虑以下事项。

资格条件

Android 正在开展一项试行计划，允许 OEM 提名的应用成为云媒体提供商。目前，只有 OEM 提名的应用才有资格参与该计划，成为 Android 的云媒体提供商。每个 OEM 最多可以指定 3 个应用。一旦获得批准，这些应用便可在任何安装了这些应用的 GMS Android 设备上作为云媒体提供程序进行访问。

Android 维护着一份服务器端列表，其中包含所有符合条件的云服务提供商。每个 OEM 都可以使用可配置的叠加层来选择默认云服务提供商。指定应用必须满足所有技术要求并通过所有质量测试。如需详细了解 OEM 云媒体提供商测试计划的流程和要求，请填写咨询表单。

确定您是否需要创建云媒体提供商

云媒体提供方是指作为用户在云端备份和检索照片和视频的主要来源的应用或服务。如果您的应用具有实用内容库，但通常不用作照片存储解决方案，则应考虑创建文档提供程序。

每份个人资料对应一个活跃的云服务提供商

每个 Android 配置文件一次最多只能有一个有效的云媒体提供程序。用户可以随时从照片选择器设置中移除或更改所选云媒体服务提供方应用。

默认情况下，Android 照片选择器会自动尝试选择云服务商。

• 如果设备上只有一个符合条件的云服务提供商，该应用将被自动选择为当前提供商。

• 如果设备上有多个符合条件的云服务提供商，并且其中一个提供商与 OEM 选择的默认应用相匹配，系统会选择 OEM 选择的应用。

• 如果设备上有多个符合条件的云服务提供商，并且它们都与 OEM 选择的默认云服务提供商都不相符，系统将不会选择任何应用。

打造您的云媒体提供商

下图说明了 Android 应用、Android 照片选择器、本地设备的 MediaProvider 和 CloudMediaProvider 之间的照片选择会话之前和期间的事件序列。

图 1：照片选择会话期间的事件序列图。

1. 系统会初始化用户的首选云服务商，并定期将媒体元数据同步到 Android 照片选择器后端。
2. 当 Android 应用启动照片选择器时，在向用户显示合并的本地或云端项网格之前，照片选择器会先执行对延迟敏感的增量同步，以便确保结果尽可能保持最新。收到响应后或到达截止时间时，照片选择器网格现在会显示所有可访问的照片，将存储在您设备本地的照片与从云端同步的照片合并在一起。
3. 当用户滚动时，照片选择器会从云媒体提供程序获取媒体缩略图，以显示在界面中。
4. 当用户完成会话并且结果包含云端媒体内容时，照片选择器会请求内容的文件描述符，生成 URI，并向调用应用授予对文件的访问权限。
5. 现在，应用能够打开 URI，并拥有对媒体内容的只读权限。默认情况下，敏感元数据会被遮盖。照片选择器利用 FUSE 文件系统来协调 Android 应用和云端媒体提供程序之间的数据交换。

常见问题

在考虑实现时，请牢记以下重要注意事项：

避免重复文件

由于 Android 照片选择器无法检查云端媒体状态，因此 CloudMediaProvider 需要在云端和本地设备上同时存在的任何文件的光标行中提供 MEDIA_STORE_URI，否则用户会在照片选择器中看到重复文件。

优化预览画面的图片大小

请务必注意，从 onOpenPreview 返回的文件不是完整分辨率的图片，并且遵循所请求的 Size。图片过大会导致界面中的加载时间，并且图片过小可能会导致像素化或模糊不清（取决于设备的屏幕尺寸）。

处理正确的屏幕方向

如果在 onOpenPreview 中返回的缩略图不包含其 EXIF 数据，则应以正确的屏幕方向返回，以避免缩略图在预览网格中错误地旋转。

防止未经授权的访问

在从 ContentProvider 将数据返回给调用方之前，检查 MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION。这样可以防止未经授权的应用访问云数据。

CloudMediaProvider 类

CloudMediaProvider 类派生自 android.content.ContentProvider，包含如下例所示的方法：

Kotlin

abstract class CloudMediaProvider : ContentProvider() {

    @NonNull
    abstract override fun onGetMediaCollectionInfo(@NonNull bundle: Bundle): Bundle

    @NonNull
    override fun onQueryAlbums(@NonNull bundle: Bundle): Cursor = TODO("Implement onQueryAlbums")

    @NonNull
    abstract override fun onQueryDeletedMedia(@NonNull bundle: Bundle): Cursor

    @NonNull
    abstract override fun onQueryMedia(@NonNull bundle: Bundle): Cursor

    @NonNull
    abstract override fun onOpenMedia(
        @NonNull string: String,
        @Nullable bundle: Bundle?,
        @Nullable cancellationSignal: CancellationSignal?
    ): ParcelFileDescriptor

    @NonNull
    abstract override fun onOpenPreview(
        @NonNull string: String,
        @NonNull point: Point,
        @Nullable bundle: Bundle?,
        @Nullable cancellationSignal: CancellationSignal?
    ): AssetFileDescriptor

    @Nullable
    override fun onCreateCloudMediaSurfaceController(
        @NonNull bundle: Bundle,
        @NonNull callback: CloudMediaSurfaceStateChangedCallback
    ): CloudMediaSurfaceController? = null
}

Java

public abstract class CloudMediaProvider extends android.content.ContentProvider {

  @NonNull
  public abstract android.os.Bundle onGetMediaCollectionInfo(@NonNull android.os.Bundle);

  @NonNull
  public android.database.Cursor onQueryAlbums(@NonNull android.os.Bundle);

  @NonNull
  public abstract android.database.Cursor onQueryDeletedMedia(@NonNull android.os.Bundle);

  @NonNull
  public abstract android.database.Cursor onQueryMedia(@NonNull android.os.Bundle);

  @NonNull
  public abstract android.os.ParcelFileDescriptor onOpenMedia(@NonNull String, @Nullable android.os.Bundle, @Nullable android.os.CancellationSignal) throws java.io.FileNotFoundException;

  @NonNull
  public abstract android.content.res.AssetFileDescriptor onOpenPreview(@NonNull String, @NonNull android.graphics.Point, @Nullable android.os.Bundle, @Nullable android.os.CancellationSignal) throws java.io.FileNotFoundException;

  @Nullable
  public android.provider.CloudMediaProvider.CloudMediaSurfaceController onCreateCloudMediaSurfaceController(@NonNull android.os.Bundle, @NonNull android.provider.CloudMediaProvider.CloudMediaSurfaceStateChangedCallback);
}

CloudMediaProviderContract 类

除了主要的 CloudMediaProvider 实现类之外，Android 照片选择器还包含 CloudMediaProviderContract 类。这个类概述了照片选择器与云媒体提供方之间的互操作性，其中涵盖了许多方面，例如用于同步操作的 MediaCollectionInfo、预期的 Cursor 列和 Bundle extra。

Kotlin

object CloudMediaProviderContract {

    const val EXTRA_ALBUM_ID = "android.provider.extra.ALBUM_ID"
    const val EXTRA_LOOPING_PLAYBACK_ENABLED = "android.provider.extra.LOOPING_PLAYBACK_ENABLED"
    const val EXTRA_MEDIA_COLLECTION_ID = "android.provider.extra.MEDIA_COLLECTION_ID"
    const val EXTRA_PAGE_SIZE = "android.provider.extra.PAGE_SIZE"
    const val EXTRA_PAGE_TOKEN = "android.provider.extra.PAGE_TOKEN"
    const val EXTRA_PREVIEW_THUMBNAIL = "android.provider.extra.PREVIEW_THUMBNAIL"
    const val EXTRA_SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED = "android.provider.extra.SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED"
    const val EXTRA_SYNC_GENERATION = "android.provider.extra.SYNC_GENERATION"
    const val MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION = "com.android.providers.media.permission.MANAGE_CLOUD_MEDIA_PROVIDERS"
    const val PROVIDER_INTERFACE = "android.content.action.CLOUD_MEDIA_PROVIDER"

    object MediaColumns {
        const val DATE_TAKEN_MILLIS = "date_taken_millis"
        const val DURATION_MILLIS = "duration_millis"
        const val HEIGHT = "height"
        const val ID = "id"
        const val IS_FAVORITE = "is_favorite"
        const val MEDIA_STORE_URI = "media_store_uri"
        const val MIME_TYPE = "mime_type"
        const val ORIENTATION = "orientation"
        const val SIZE_BYTES = "size_bytes"
        const val STANDARD_MIME_TYPE_EXTENSION = "standard_mime_type_extension"
        const val STANDARD_MIME_TYPE_EXTENSION_ANIMATED_WEBP = 3 // 0x3
        const val STANDARD_MIME_TYPE_EXTENSION_GIF = 1 // 0x1
        const val STANDARD_MIME_TYPE_EXTENSION_MOTION_PHOTO = 2 // 0x2
        const val STANDARD_MIME_TYPE_EXTENSION_NONE = 0 // 0x0
        const val SYNC_GENERATION = "sync_generation"
        const val WIDTH = "width"
    }

    object AlbumColumns {
        const val DATE_TAKEN_MILLIS = "date_taken_millis"
        const val DISPLAY_NAME = "display_name"
        const val ID = "id"
        const val MEDIA_COUNT = "album_media_count"
        const val MEDIA_COVER_ID = "album_media_cover_id"
    }

    object MediaCollectionInfo {
        const val ACCOUNT_CONFIGURATION_INTENT = "account_configuration_intent"
        const val ACCOUNT_NAME = "account_name"
        const val LAST_MEDIA_SYNC_GENERATION = "last_media_sync_generation"
        const val MEDIA_COLLECTION_ID = "media_collection_id"
    }
}

Java

public final class CloudMediaProviderContract {

  public static final String EXTRA_ALBUM_ID = "android.provider.extra.ALBUM_ID";
  public static final String EXTRA_LOOPING_PLAYBACK_ENABLED = "android.provider.extra.LOOPING_PLAYBACK_ENABLED";
  public static final String EXTRA_MEDIA_COLLECTION_ID = "android.provider.extra.MEDIA_COLLECTION_ID";
  public static final String EXTRA_PAGE_SIZE = "android.provider.extra.PAGE_SIZE";
  public static final String EXTRA_PAGE_TOKEN = "android.provider.extra.PAGE_TOKEN";
  public static final String EXTRA_PREVIEW_THUMBNAIL = "android.provider.extra.PREVIEW_THUMBNAIL";
  public static final String EXTRA_SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED = "android.provider.extra.SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED";
  public static final String EXTRA_SYNC_GENERATION = "android.provider.extra.SYNC_GENERATION";
  public static final String MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION = "com.android.providers.media.permission.MANAGE_CLOUD_MEDIA_PROVIDERS";
  public static final String PROVIDER_INTERFACE = "android.content.action.CLOUD_MEDIA_PROVIDER";
}

// Columns available for every media item
public static final class CloudMediaProviderContract.MediaColumns {

  public static final String DATE_TAKEN_MILLIS = "date_taken_millis";
  public static final String DURATION_MILLIS = "duration_millis";
  public static final String HEIGHT = "height";
  public static final String ID = "id";
  public static final String IS_FAVORITE = "is_favorite";
  public static final String MEDIA_STORE_URI = "media_store_uri";
  public static final String MIME_TYPE = "mime_type";
  public static final String ORIENTATION = "orientation";
  public static final String SIZE_BYTES = "size_bytes";
  public static final String STANDARD_MIME_TYPE_EXTENSION = "standard_mime_type_extension";
  public static final int STANDARD_MIME_TYPE_EXTENSION_ANIMATED_WEBP = 3; // 0x3
  public static final int STANDARD_MIME_TYPE_EXTENSION_GIF = 1; // 0x1 
  public static final int STANDARD_MIME_TYPE_EXTENSION_MOTION_PHOTO = 2; // 0x2 
  public static final int STANDARD_MIME_TYPE_EXTENSION_NONE = 0; // 0x0 
  public static final String SYNC_GENERATION = "sync_generation";
  public static final String WIDTH = "width";
}

// Columns available for every album item
public static final class CloudMediaProviderContract.AlbumColumns {

  public static final String DATE_TAKEN_MILLIS = "date_taken_millis";
  public static final String DISPLAY_NAME = "display_name";
  public static final String ID = "id";
  public static final String MEDIA_COUNT = "album_media_count";
  public static final String MEDIA_COVER_ID = "album_media_cover_id";
}

// Media Collection metadata that is cached by the OS to compare sync states.
public static final class CloudMediaProviderContract.MediaCollectionInfo {

  public static final String ACCOUNT_CONFIGURATION_INTENT = "account_configuration_intent";
  public static final String ACCOUNT_NAME = "account_name";
  public static final String LAST_MEDIA_SYNC_GENERATION = "last_media_sync_generation";
  public static final String MEDIA_COLLECTION_ID = "media_collection_id";
}

onGetMediaCollectionInfo

操作系统使用 onGetMediaCollectionInfo() 方法评估其缓存的云媒体项的有效性，并确定是否需要与云媒体提供商进行同步。由于操作系统可能会频繁调用 onGetMediaCollectionInfo()，因此 onGetMediaCollectionInfo() 被认为对性能至关重要；因此，避免长时间运行的操作或可能会对性能产生负面影响的附带效应至关重要。操作系统会缓存来自此方法的先前响应，并将其与后续响应进行比较，以确定适当的操作。

Kotlin

abstract fun onGetMediaCollectionInfo(extras: Bundle): Bundle

Java

@NonNull
public abstract Bundle onGetMediaCollectionInfo(@NonNull Bundle extras);

返回的 MediaCollectionInfo 软件包包含以下常量：

• MEDIA_COLLECTION_ID
• LAST_MEDIA_SYNC_GENERATION
• ACCOUNT_NAME
• ACCOUNT_CONFIGURATION_INTENT

onQueryMedia

onQueryMedia() 方法用于在各种视图中填充照片选择器中的主照片网格。这些调用可能对延迟敏感，并且可能会在后台主动同步中被调用，或者在需要完全或增量同步状态时在照片选择器会话期间被调用。照片选择器界面不会无限期地等待响应显示结果，并且可能会出于界面目的而超时这些请求。返回的游标仍会尝试处理到照片选择器的数据库中，以供将来的会话使用。

此方法会返回一个 Cursor，它表示媒体集合中的所有媒体内容，可视需要按提供的 extra 进行过滤，并按 MediaColumns#DATE_TAKEN_MILLIS 的时间倒序排序（最近的内容最先显示）。

返回的 CloudMediaProviderContract 软件包包含以下常量：

• EXTRA_ALBUM_ID
• EXTRA_LOOPING_PLAYBACK_ENABLED
• EXTRA_MEDIA_COLLECTION_ID
• EXTRA_PAGE_SIZE
• EXTRA_PAGE_TOKEN
• EXTRA_PREVIEW_THUMBNAIL
• EXTRA_SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED
• EXTRA_SYNC_GENERATION
• MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION
• PROVIDER_INTERFACE

云媒体提供商必须将 CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID 设置为返回的 Bundle 的一部分。如果未设置，便会产生错误，并会使返回的 Cursor 失效。如果云媒体提供程序处理了提供的 extra 中的任何过滤器，则必须将键作为返回的 Cursor#setExtras 的一部分添加到 ContentResolver#EXTRA_HONORED_ARGS。

onQueryDeletedMedia

onQueryDeletedMedia() 方法用于确保云端账号中删除的内容从照片选择器界面中正确移除。由于其潜在的延迟敏感性，这些调用可能是通过以下操作发起的：

• 后台主动同步
• 照片选择器会话（当需要完全或增量同步状态时）

照片选择器的界面会优先考虑响应式用户体验，不会无限期地等待响应。为了保持顺畅的互动，可能会发生超时。系统仍会尝试处理返回的所有 Cursor，以供将来的会话处理到照片选择器的数据库中。

此方法会返回一个 Cursor，它表示 onGetMediaCollectionInfo() 返回的当前提供程序版本内整个媒体集合中所有已删除的媒体项。您可以选择按 extra 过滤这些项。云媒体提供商必须将 CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID 设为返回的 Cursor#setExtras 的一部分。如果不设置，这会产生错误，会导致 Cursor 失效。如果提供程序处理了所提供的 extra 中的任何过滤器，则必须将键添加到 ContentResolver#EXTRA_HONORED_ARGS。

onQueryAlbums

onQueryAlbums() 方法用于提取云服务提供商提供的 Cloud 影集列表及其关联的元数据。如需了解详情，请参阅 CloudMediaProviderContract.AlbumColumns。

此方法会返回一个 Cursor，它表示媒体集合中的所有专辑项，均可选择按提供的 extra 进行过滤，并按 AlbumColumns#DATE_TAKEN_MILLIS 的时间倒序排序，最新的项排在最前面。云媒体提供商必须将 CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID 设为返回的 Cursor 的一部分。如果未设置，便会产生错误，并会使返回的 Cursor 失效。如果提供程序处理了所提供的 extra 中的任何过滤器，则必须将密钥作为返回的 Cursor 的一部分添加到 ContentResolver#EXTRA_HONORED_ARGS。

onOpenMedia

onOpenMedia() 方法应返回由提供的 mediaId 标识的完整尺寸的媒体。如果此方法在将内容下载到设备时阻塞，您应定期检查提供的 CancellationSignal 以中止已放弃的请求。

onOpenPreview

onOpenPreview() 方法应针对提供的 mediaId 的项目返回提供的 size 的缩略图。缩略图应采用原始 CloudMediaProviderContract.MediaColumns#MIME_TYPE 格式，并且分辨率应该远低于 onOpenMedia 返回的内容。如果此方法在下载内容到设备时被屏蔽，则应定期检查提供的 CancellationSignal 以中止放弃的请求。

onCreateCloudMediaSurfaceController

onCreateCloudMediaSurfaceController() 方法应返回用于呈现媒体内容预览的 CloudMediaSurfaceController，如果不支持预览呈现，则会返回 null。

CloudMediaSurfaceController 负责在 Surface 的给定实例上渲染媒体内容预览。此类的方法是异步的，不应因执行任何繁重操作而阻塞。单个 CloudMediaSurfaceController 实例负责渲染与多个 surface 关联的多项媒体内容。

CloudMediaSurfaceController 支持以下生命周期回调列表：

• onConfigChange
• onDestroy
• onMediaPause
• onMediaPlay
• onMediaSeekTo
• onPlayerCreate
• onPlayerRelease
• onSurfaceChanged
• onSurfaceCreated
• onSurfaceDestroyed