智能媒体管理产品文档转换/预览功能介绍(4)--快速搭建

2021-09-07 05:43:42

一、导语

智能媒体管理提供了 Cloud Native 架构的文档转换/预览服务，本文介绍快速搭建的示例，让您用 DIY 的体验方式实现文档预览功能。

二、环境准备

2.1 准备 RAM 子账号

为了实现安全的文档转换/预览功能，本文使用 RAM 子账号来管理资源并进行代码开发。

2.1.1 创建 test 子账号

登陆访问控制页面，点击“用户管理”，选择“新建用户”，创建子账号 test ，创建成功如下图所示：

2.1.2 子账号授权

在创建子账号成功后的界面，选择 test 子账号，点击“授权”，确保给该子账号授予如下策略：

AliyunOSSFullAccess。具有完整访问 OSS 的权限，让文档转换能够在 OSS 存储转换数据。本文为了快速搭建而选择此权限，如果需要更精细的权限控制，可以参考 OSS 子账号设置常见问题。
AliyunSTSAssumeRoleAccess。具有申请 STS Token的权限，预览时为客户端提供 STS Token，从而保证前端访问 OSS 的安全性。
AliyunIMMFullAccess。具有执行 IMM 服务的权限，具有了该权限就可以调用文档转换接口。

2.1.3 生成子账号的AK（Access Key）

代码开发时，需要使用AK（Access Key）。在 2.1.1章节创建子账号成功后的界面，选择 test 子账号，点击“管理”，进入 test 子账号后再点击“创建 AccessKey”，保存好 AccessKey ID 和 Secret，它们将用于代码开发。
注意：目前每个子账号最多使用2个 AK，可以通过删除旧的 AK 来解决。

如上图中，得到 AK ID 类似 LTAIxxxxxxxxxxx，对应的 AK Secret 类似 W1yyyyyyyyyyyyyyyyyyyy。
注意：这里提供的值只是示例，不能直接使用，具体的值请您在控制台获取并保存。

2.2 准备 OSS 服务

文档转换/预览是基于 OSS 实现，需要 OSS 的存储空间支持，本文通过创建新桶来实现，如下图所示。

在华东2（上海区域）创建了 yourid-dev-imm 桶。
注意1：该桶名只是示例，不能直接使用，需要替换为您的桶名。
注意2：如果预览服务的域名和 OSS 桶域名不同，需要设置 OSS 的 CORS 功能，允许预览服务器访问，配置细节请参考文档预览。

2.3 准备 IMM 服务

转换/预览使用 IMM 服务，先开通产品产品，然后创建项目，如下图所示，在华东2（上海区域）创建了 imm 项目。

注意：一定需保证创建 IMM 项目 时指定的 Region 要和您创建 OSS 桶指定的区域相同，才能够正常工作，目的是避免转换时带来跨 OSS Region 访问的流量费用。

2.4 准备开发环境

本文基于 “IntelliJ IDEA + Maven” 准备 Java 开发环境，参考 IMM 服务的 Java SDK 文档。
注意：在 pom.xml 文件中添加 aliyun-java-sdk-core 和 aliyun-java-sdk-imm 的版本依赖。

 <dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <optional>true</optional>
    <version>3.5.1</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-imm</artifactId>
    <optional>true</optional>
    <version>1.5.0</version>
</dependency>

三、开发部署

3.1 转换代码

环境准备好后，可以参考如下 Java 代码实现文档转换，技术细节请参考转换原理。

import com.aliyuncs.imm.main.IMMClient;
import com.aliyuncs.imm.model.v20170906.*;
import com.aliyuncs.exceptions.*;

public class TestImmOffice {
    public static void main(String[] args) {
        String accessKeyId = "LTAIxxxxxxxxxxx";  //RAM 中 test 子账号的 AK ID
        String accessKeySecret = "W1yyyyyyyyyyyyyyyyyyyy"; //RAM 中 test 子账号的 AK Secret

        IMMClient client = new IMMClient("cn-shanghai", accessKeyId, accessKeySecret);
        CreateOfficeConversionTaskResponse resp = new CreateOfficeConversionTaskResponse();
        CreateOfficeConversionTaskRequest req = new CreateOfficeConversionTaskRequest();
        req.setProject("IMM");   //在 IMM 中创建的项目
        req.setSrcUri("oss://yourid-dev-imm/test-data/office/paxos.pptx");   //OSS 源文件路径
        req.setTgtUri("oss://yourid-dev-imm/test-data/office/paxos.pptx/output");  //OSS 转换文件路径
        req.setTgtType("vector");

        try {
            resp = client.getResponse(req);
            System.out.printf("requestId=%s, taskId=%s, tgtloc=%s", resp
                    .getRequestId(), resp.getTaskId(),resp.getTgtLoc());
        }catch (ClientException e){
            System.out.println("error");
        }
    }
}

转换成功后，您将在 OSS 的 yourid-dev-imm 桶（华东2---上海区域），对应 test-data/office/paxos.pptx/output/doc 目录下（注意：转换引擎增加了 doc后缀），得到 meta.json , fp*.json, 以及 I 目录下的文件。

3.2 预览部署

转换成功后，直接使用“智能媒体管理”服务提供的预览渲染引擎，地址为 https://preview.imm.aliyun.com/index.html ，确认参考文档预览配置存储转换数据的 OSS 桶支持 CORS。

3.3 前端访问

部署预览引擎后，前端就可以通过访问预览引擎所在 OSS 桶的域名，实现预览功能。基于上述章节介绍，将使用 https://preview.imm.aliyun.com/index.html 路径访问渲染引擎。

注意：https://preview.imm.aliyun.com/index.html 是智能媒体管理服务提供的渲染引擎。

3.3.1 OSS 公共读权限预览

为了快速体验预览引擎的效果，我们简化 OSS 的权限配置为公共读，如下图所示。

此时，可以通过如下地址格式完成文档预览。

https://preview.imm.aliyun.com/index.html
?url=https://yourid-dev-imm.oss-cn-shanghai.aliyuncs.com/test-data/office/paxos.pptx/output    //无需在output后加'/'
&region=oss-cn-shanghai    //转换数据所在桶的region
&bucket=yourid-dev-imm    //转换数据所在桶
&copy=1    //预览时可以选择并拷贝里面的文字

其中 ? 前面部分为访问渲染引擎的路径，而 url=xxx 为转换文档的目标地址（注意：在 output 后无需加上 /，渲染引擎会自动处理）， region=oss-cn-shanghai 表示 OSS 桶所在区域，bucket=yourid-dev-imm 为桶名。
注意：实际使用时，需要把 yourid-dev-imm 更换为自己的桶。

3.3.2 OSS 私有权限预览（高安全）

设置桶为私有，但让渲染引擎 preview目录下的文件为公共读，然后为转换文件申请STS Token

policy = {
    "Version": "1",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "oss:*"
        ],
        "Resource": [
          "acs:oss:*:" + accountId + ":" + bucket + "/" + prefix + "/*"
        ]
      },
      {
        "Effect": "Allow",
        "Action": [
          "oss:ListObjects"
        ],
        "Resource": [
          "acs:oss:*:" + accountId + ":" + bucket
        ],
        "Condition": {
          "StringLike": {
            "oss:Prefix": prefix + "/*"
          }
        }
      }
    ]
  }

此时把 accountId 设置为 * ，表示任意用户；bucket 设置为 yourid-dev-imm ，表示您自己创建的桶；prefix 设置为本文中的路径 test-data/office/paxos.pptx/output。然后，调用 STS 的 AssumeRole 得到 AccessKeyId，AccessKeySecret，SecurityToken三元组，然后用如下方式组合，即可实现安全的预览访问。

https://preview.imm.aliyun.com/index.html
?url=https://yourid-dev-imm.oss-cn-shanghai.aliyuncs.com/test-data/office/paxos.pptx/output    //无需在output后加'/'
&accessKeyId=STS.AAAAAAAAAA    //STS返回的AccessKeyId，注意access小写
&accessKeySecret=BBBBBBBBBBB    //STS返回的AccessKeySecret，注意access小写
&stsToken=CCCCCCCCCCCCC    //CCCCCCCCCCCCC是encode(STS返回的SecurityToken)得到的结果，不直接使用
&region=oss-cn-shanghai    //转换数据所在桶的region
&bucket=yourid-dev-imm    //转换数据所在桶
&copy=1    //预览时可以选择并拷贝里面的文字
&...

注意1：copy=1表示预览时可以选择并拷贝里面的文字，copy=0则禁止选择和拷贝。
注意2：stsToken 字段，需要在STS返回的SecurityToken基础上使用encode处理，然后再拼到上述URL中。

如下是采用 nodeJS 拼出预览 URL的代码示例：

function parse(params){
  return Object.keys(params).map((key) => {
    return `${key}=${params[key]}`;
  }).join("&");
}

var params = {};
params.url = "https://yourid-dev-imm.oss-cn-shanghai.aliyuncs.com/test-data/office/paxos.pptx/output";
params.accessKeyId = "STS.AAAAAAAAAA";    //STS.AAAAAAAAAA是调用STS的AssumeRole()返回的AccessKeyId
params.region = "oss-cn-shanghai";
params.accessKeySecret = "BBBBBBBBBBB";    //BBBBBBBBBBB是调用STS的AssumeRole()返回的AccessKeySecret
params.stsToken = encodeURIComponent("STS.stsToken");  //STS.stsToken是调用STS的AssumeRole返回的SecurityToken
params.region = "oss-cn-shanghai";
params.bucket = "yourid-dev-imm";
var url = `https://yourid-dev-imm.oss-cn-shanghai.aliyuncs.com/preview/index.html?${parse(params)}`

更多详细信息，请参考文档转换和预览 FAQ 。

四、参考文档

参考如下的文章，帮助您掌握相关背景：

码农公寓