为 Android 创建云媒体提供程序

云媒体提供程序会为 Android 照片选择器提供额外的云媒体内容。当应用使用 ACTION_PICK_IMAGES 或 ACTION_GET_CONTENT 请求用户的媒体文件时，用户可以选择云媒体提供程序提供的照片或视频。云媒体提供程序还可以提供关于相册的信息，这些信息可以在 Android 照片选择器中浏览。

准备工作

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

资格要求

Android 正在运行一个试点计划，允许 OEM 提名的应用成为云媒体提供程序。目前只有 OEM 提名的应用有资格参与此计划成为 Android 的云媒体提供程序。每个 OEM 最多可以提名 3 个应用。一旦获得批准，这些应用就可以在安装了它们的任何 GMS Android 设备上作为云媒体提供程序访问。

Android 维护着所有符合条件的云提供程序的服务器端列表。每个 OEM 可以使用可配置的 overlay 选择默认云提供程序。提名的应用必须满足所有技术要求并通过所有质量测试。要详细了解 OEM 云媒体提供程序试点计划的流程和要求，请填写咨询表单。

确定是否需要创建云媒体提供程序

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

每个配置文件只能有一个活动的云提供程序

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

默认情况下，Android 照片选择器将尝试自动选择云提供程序。

如果设备上只有一个符合条件的云提供程序，该应用将自动选作当前提供程序。
如果设备上有多个符合条件的云提供程序，并且其中一个与 OEM 选择的默认提供程序匹配，则将选择 OEM 选择的应用。
如果设备上有多个符合条件的云提供程序，并且它们都不与 OEM 选择的默认提供程序匹配，则不会选择任何应用。

构建您的云媒体提供程序

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

Sequence diagram showing flow from photo picker to a cloud media provider — **图 1：**照片选择会话期间的事件序列图。

系统初始化用户的首选云提供程序，并定期将媒体元数据同步到 Android 照片选择器后端。
当 Android 应用启动照片选择器时，在向用户显示合并的本地或云端项目网格之前，照片选择器会与云提供程序执行延迟敏感的增量同步，以确保结果尽可能最新。收到响应后，或达到截止时间时，照片选择器网格会显示所有可访问的照片，这些照片结合了本地存储在设备上的照片和从云端同步的照片。
当用户滚动时，照片选择器会从云媒体提供程序获取媒体缩略图以在界面中显示。
当用户完成会话且结果包含云媒体项目时，照片选择器会请求内容的文件描述符，生成 URI，并授予调用应用对该文件的访问权限。
应用现在可以打开该 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() 被认为是性能关键型的；避免长时间运行的操作或可能对性能产生负面影响的副作用至关重要。操作系统会缓存此方法的先前响应，并将其与后续响应进行比较，以确定适当的操作。

Kotlin

abstract fun onGetMediaCollectionInfo(extras: Bundle): Bundle

Java

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

返回的 MediaCollectionInfo bundle 包含以下常量

onQueryMedia

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

此方法返回一个 Cursor，表示媒体集合中的所有媒体项目，可选择通过提供的 extras 进行过滤，并按 MediaColumns#DATE_TAKEN_MILLIS 的倒序排列（最新项目优先）。

返回的 CloudMediaProviderContract bundle 包含以下常量

云媒体提供程序必须将 CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID 设置为返回的 Bundle 的一部分。未设置此值是一个错误，并且会使返回的 Cursor 无效。如果云媒体提供程序处理了提供的 extras 中的任何过滤器，它必须将该 key 添加到返回的 Cursor#setExtras 的 ContentResolver#EXTRA_HONORED_ARGS 中。

onQueryDeletedMedia

onQueryDeletedMedia() 方法用于确保云账户中已删除的项目从照片选择器用户界面中正确移除。由于它们可能对延迟敏感，这些调用可能会作为以下部分发起：

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

照片选择器的用户界面优先考虑响应迅速的用户体验，不会无限期等待响应。为保持流畅的交互，可能会发生超时。任何返回的 Cursor 仍将尝试处理到照片选择器的数据库中以供将来的会话使用。

此方法返回一个 Cursor，表示在当前提供程序版本中整个媒体集合中所有已删除的媒体项目，该版本由 onGetMediaCollectionInfo() 返回。这些项目可以可选地通过 extras 进行过滤。云媒体提供程序必须将 CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID 设置为返回的 Cursor#setExtras 的一部分。未设置此值是一个错误，并且会使 Cursor 无效。如果提供程序处理了提供的 extras 中的任何过滤器，它必须将该 key 添加到 ContentResolver#EXTRA_HONORED_ARGS 中。

onQueryAlbums

onQueryAlbums() 方法用于获取云提供程序中可用的云相册列表及其相关元数据。有关更多详细信息，请参阅 CloudMediaProviderContract.AlbumColumns。

此方法返回一个 Cursor，表示媒体集合中的所有相册项目，可选择通过提供的 extras 进行过滤，并按 AlbumColumns#DATE_TAKEN_MILLIS 的倒序排列（最新项目优先）。云媒体提供程序必须将 CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID 设置为返回的 Cursor 的一部分。未设置此值是一个错误，并且会使返回的 Cursor 无效。如果提供程序处理了提供的 extras 中的任何过滤器，它必须将该 key 添加到返回的 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 支持以下生命周期回调列表

创建自定义文档提供程序

为 Android 创建云媒体提供程序 通过收藏保持井井有条 根据您的偏好保存内容并进行分类。

准备工作

资格要求

确定是否需要创建云媒体提供程序

每个配置文件只能有一个活动的云提供程序

构建您的云媒体提供程序

常见问题

避免重复文件

优化图像大小以用于预览显示

处理正确的方向

防止未经授权的访问

CloudMediaProvider 类

Kotlin

Java

CloudMediaProviderContract 类

Kotlin

Java

onGetMediaCollectionInfo

Kotlin

Java

onQueryMedia

onQueryDeletedMedia

onQueryAlbums

onOpenMedia

onOpenPreview

onCreateCloudMediaSurfaceController

为 Android 创建云媒体提供程序