目录

开启文件变化通知

场景介绍

华为云空间服务提供当文件发生变化时推送通知能力,从而保持云端与本地文件同步。使用Changes功能需要开发者实现可实时接收变化的Server服务器,该Server可以接收变化并将变化信息实时推送给相应的客户端,客户端接收消息后可以及时刷新变化。

开启文件变化通知

  1. 开发者实现可以接收文件变化的Server服务器,需要将该Server的地址注册到Drive,Drive在发送变化消息时需要校验Server地址的有效性。

    将Server服务器域名注册到Drive方法如下图:

    1. 登录AppGallery Connect网站,点击“我的项目”。
    2. 找到“构建 > 云空间服务”。如果“构建”下无“云空间服务”,可点击左下角“全部功能”按钮,在“构建”中找到“云空间服务”,然后点击图标添加。

  2. 您的Server服务器需要能解析Drive发送的文件变化消息,Drive消息的消息头格式如下:

    参数

    类型

    必选/可选

    说明

    X-HW-Channel-ID

    varchar(255)

    必选

    开发者指定的,通过Changes.Subscribe接口上报给Drive服务器的用户唯一标识。

    X-HW-Channel-Token

    varchar(255)

    可选

    调用changes.subscribe接口时自定义的userToken,Server需要对userToken进行校验。

    X-HW-Channel-Expiration

    varchar(255)

    可选

    Channel通知到期的日期和时间

    格式例如:Tue,18 Jun 2019 14:21:46 GMT。

    X-HW-Resource-ID

    varchar(255)

    必选

    资源ID,Channel标识,当该资源变化时会推送通知。

    X-HW-Resource-URI

    varchar(255)

    必选

    资源版本标识符。

    X-HW-Resource-State

    varchar(255)

    必选

    资源状态,可选值:

    sync:订阅成功,Channel创建成功。

    add:资源增加。

    remove:资源被删除。

    update:资源属性被更新。

    recycle:资源移动到回收站。

    unrecycle:资源从回收站移出。

    change:资源变化。

    X-HW-Message-Number

    varchar(255)

    必选

    消息号,后面的消息总是大于前面的,但是并不是连续的。Sync消息总是为1。

    X-HW-Changed

    varchar(255)

    可选

    Change的详细信息,state为update时有效,可选值。

    content: 资源内容更新。

    properties: 资源属性更新。

    parents: 资源的父目录变化,暂时不涉及。

    children: 资源的子文件变化。

  3. 您的Server服务器下发变化通知应用。

    您的Server服务器能够将Drive发送的变化消息下发通知到应用,让应用刷新变化内容;Drive不限制您的Server服务器下发变化通知的实现方式,但推荐开发者使用华为推送服务,华为推送服务已经实现了将服务器消息推送到指定应用的功能,使用华为推送服务需要对接HMS Core Push SDK,具体参见《消息推送服务》。若不使用华为推送服务,则不需要集成HMS Core Push SDK,但您的Server服务器需要自己实现消息推送的功能。

  4. 获取StartCursor,通过subscribe注册推送通知功能。

    应用调用Changes.getStartCursor接口,获取Changes.subscribe需要使用的cursor值,调用Changes.subscribe接口注册当文件变化时推送通知功能,该接口会返回注册成功后的Channel对象,开发者需要将Channel中的userToken回传您的Server服务器,用于后续您的Server服务器接口消息的鉴权使用,同时开发者可以根据该Channel进行后续的刷新变化、停止推送通知等接口处理。

    功能简介:

    Changes.subscribe接口实现订阅目录或文件变化的功能,主要是针对用户维度所有资源的变化。

    限制

    • 必填参数:fileId, cursor,id,type,url。
    • id只支持大小写字母及数字的组合,且长度不超过256个字符。
    • url参数采用允许清单机制,只支持设置在允许清单中的url。允许清单中url的设置通过AGC网页添加,以www格式开头,仅支持https协议。因此本接口请求体中的url需要以https://格式开头。
    • type,只支持 web_hook。
    • expirationTime ,UTC时间戳,默认一小时。
    • 仅支持80/8080/443/8443/8888此范围内端口回调
    • scope至少包含下面其中一个:
      • https://www.huawei.com/auth/drive.file
      • https://www.huawei.com/auth/drive
      • https://www.huawei.com/auth/drive. readonly
      • https://www.huawei.com/auth/drive. metadata
      • https://www.huawei.com/auth/drive. metadata.readonly

    说明

    回调url通知变更消息使用POST请求。

    获取startCursor请求样例:

    GET  https://driveapis.cloud.huawei.com.cn/drive/v1/changes/getStartCursor?fields=*    HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer CV3PnPLZXyr9K2GV7RYZkF962JZvoEkMQhTho3QHQAPQUyma/lEyZskP/IMWrc7FvaeHivO7y0lyibI/fQvulBnTgtXArSVPsjaLKvYNkDsJSaIR2/sx+K40bYDWWpKFvJNKg2U47jRwz2mfiF3ortNk
    Cache-Control: no-cache

    响应:

    HTTP/1.1 200 OK
    {
        "category": "drive#startCursor",
        "startCursor": "238247332125117440"
    }

    Changes.subscribe接口请求样例:

    POST  https://driveapis.cloud.huawei.com.cn/drive/v1/changes/subscribe?cursor=238247332125117440&fields=*   HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer CV3PnPLZXyr9K2GV7RYZkF962JZvoEkMQhTho3QHQAPQUyma/lEyZskP/IMWrc7FvaeHivO7y0lyibI/fQvulBnTgtXArSVPsjaLKvYNkDsJSaIR2/sx+K40bYDWWpKFvJNKg2U47jRwz2mfiF3ortNk
    Cache-Control: no-cache
    
    {
        "url": "https://www.huawei.com",
        "expirationTime": 1574674540000,//设置为当前时间0-7天内,unix时间戳;不填默认为1小时
        "id": "46TMU",
        "type": "web_hook",
        "userToken": "Qeqqn"
    }

    响应:

    HTTP/1.1 200 OK
    {
        "resourceId": "MTIzMzIyMjQ1ODI0Nzc0MTgyNA",
        "category": "api#channel",
        "expirationTime": 1574674540000,
        "id": "46TMU",
        "resourceUri": "https://drive.hicloud.com/drive/v1/changes?pageSize=10&cursor=238247332125117440&form=json",
        "userToken": "Qeqqn"
    }   

  5. 获取用户文件变化。

    您的应用收到下发的通知后,调用Changes.list接口,获取用户文件变化,注意cursor入参为之前subscribe时传入的cursor。

    Changes.list接口请求样例:

    GET  https://driveapis.cloud.huawei.com.cn/drive/v1/changes?cursor=238247332125117440&fields=*   HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer CV3PnPLZXyr9K2GV7RYZkF962JZvoEkMQhTho3QHQAPQUyma/lEyZskP/IMWrc7FvaeHivO7y0lyibI/fQvulBnTgtXArSVPsjaLKvYNkDsJSaIR2/sx+K40bYDWWpKFvJNKg2U47jRwz2mfiF3ortNk
    Cache-Control: no-cache
     

    响应:

    HTTP/1.1 200 OK
    {
        "changes":[
            {
                "deleted":false,
                "file":{
                    "fileName":"W27",
                    "editedByMe":true,
                    "description":"folder",
                    "owners":[
                        {
                            "permissionId":"233228122990838144",
                            "displayName":"*******3121@**3.com",
                            "me":true,
                            "category":"drive#user"
                        }
                    ],
                    "hasShared":false,
                    "mimeType":"application/vnd.huawei-apps.folder",
                    "permissionIds":[
                        "233228122990838144"
                    ],
                    "directlyRecycled":false,
                    "recycled":false,
                    "permissions":[
                        {
                            "role":"owner",
                            "deleted":false,
                            "displayName":"*******3121@**3.com",
                            "id":"233228122990838144",
                            "category":"drive#permission",
                            "type":"user"
                        }
                    ],
                    "editedByMeTime":"2020-06-15T09:43:59Z",
                    "createdTime":"2020-06-15T09:43:59Z",
                    "id":"Bruy7elw_fApIT4Fyj2FIVa3QLMeiv32K",
                    "capabilities":{
                        "downloadPermission":true,
                        "renameFilePermission":true,
                        "commentPermission":true,
                        "deletePermission":true,
                        "readHistoryVersionPermission":true,
                        "recyclePermission":true,
                        "addChildNodePermission":true,
                        "unrecyclePermission":true,
                        "writerHasChangeCopyPermission":false,
                        "copyPermission":false,
                        "editContentPermission":true,
                        "removeChildNodePermission":true,
                        "editPermission":true,
                        "listChildNodePermission":true,
                        "shareFilePermission":true
                    },
                    "ownedByMe":true,
                    "version":1,
                    "viewedByMe":false,
                    "writersHasSharePermission":false,
                    "iconDownloadLink":"https://event-dre.dbankcdn.com/filemanagerpic/20191114091142H5kH.png",
                    "editedTime":"2020-06-15T09:43:59Z",
                    "writerHasCopyPermission":false,
                    "lastEditor":{
                        "permissionId":"233228122990838144",
                        "displayName":"*******3121@**3.com",
                        "me":true,
                        "category":"drive#user",
                        "userId":"4130049000000002265"
                    },
                    "existThumbnail":false,
                    "containers":[
                        "drive"
                    ],
                    "category":"drive#file",
                    "favorite":false
                },
                "changeType":"File",
                "time":"2020-06-15T09:43:59Z",
                "category":"drive#change",
                "type":"File",
                "fileId":"Bruy7elw_fApIT4Fyj2FIVa3QLMeiv32K"
            }
        ],
        "newStartCursor":"2312",
        "category":"drive#changeList"
    }