为 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在照片选择会话之前和期间的事件顺序。

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

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

常见问题

在考虑您的实现时，请记住以下一些重要事项。

避免重复文件

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

优化图像大小以进行预览显示

从onOpenPreview返回的文件不是全分辨率图像，并且符合正在请求的Size非常重要。图像过大会在 UI 中导致加载时间过长，而图像过小可能会根据设备的屏幕尺寸出现像素化或模糊。

处理正确的方向

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

防止未经授权的访问

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

CloudMediaProvider 类

继承自android.content.ContentProvider，CloudMediaProvider 类包含如下示例所示的方法

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附加信息。

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 包含以下常量

onQueryMedia

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

此方法返回一个Cursor，该游标表示媒体集合中所有媒体项（可以选择通过提供的附加信息进行筛选，并按MediaColumns#DATE_TAKEN_MILLIS的逆时间顺序排序，最新的项目排在最前面）。

返回的CloudMediaProviderContract 包含以下常量

云媒体提供程序必须将CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID设置为返回的Bundle的一部分。未设置此项是错误，并且会使返回的Cursor无效。如果云媒体提供程序处理了提供的附加信息中的任何筛选器，则必须将键添加到返回的Cursor#setExtras中的ContentResolver#EXTRA_HONORED_ARGS。

onQueryDeletedMedia

onQueryDeletedMedia() 方法用于确保正确地从照片选择器用户界面中删除云帐户中的已删除项目。由于它们潜在的延迟敏感性，这些调用可能作为以下部分启动：

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

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

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

onQueryAlbums

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

此方法返回一个Cursor，该游标表示媒体集合中所有相册项目（可以选择通过提供的附加信息进行筛选，并按AlbumColumns#DATE_TAKEN_MILLIS的逆时间顺序排序，最新的项目排在最前面）。云媒体提供程序必须将CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID设置为返回的Cursor的一部分。未设置此项是错误，并且会使返回的Cursor无效。如果提供程序处理了提供的附加信息中的任何筛选器，则必须将键添加到返回的Cursor中的ContentResolver#EXTRA_HONORED_ARGS。

onOpenMedia

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

onOpenPreview

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

onCreateCloudMediaSurfaceController

onCreateCloudMediaSurfaceController() 方法应返回一个用于渲染媒体项目预览的CloudMediaSurfaceController，如果预览渲染不受支持，则返回null。

CloudMediaSurfaceController管理在给定的Surface实例上渲染媒体项目的预览。此类的方法旨在异步执行，不应通过执行任何繁重操作来阻塞。单个CloudMediaSurfaceController实例负责渲染与多个surface关联的多个媒体项目。

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

上一步

创建自定义文档提供程序