文档在线预览功能由智能媒体管理(IMM)提供,支持多种文档格式的实时预览。用户可将文档存储在对象存储服务(OSS)中实现随时随地的在线预览。目前,文档服务接口存在多个版本,您可以通过本文了解从OSS数据处理模块智能媒体迁移至文档在线预览的相关步骤。
背景信息
智能媒体管理(IMM)后续新增功能及优化将以新版为主,旧版将逐步下线。由智能媒体管理(IMM)提供的媒体处理、文档处理、图片智能及文件处理等 x-oss-process 数据处理能力的所有接口均采用新版智能媒体管理。
前提条件
IMM Project需要跟Bucket在同一地域下。
需要您绑定自定义域名至Bucket默认域名,通过自定义域名访问文件时才能打开预览。
如提示域名未配置至小程序的WebView白名单,请通过钉钉用户群(钉钉群号:88490020073)联系智能媒体管理技术支持。技术支持人员将根据用户提供的微信可信域名验证文件进行白名单配置。
如何迁移
您可以按照以下步骤进行迁移:
在控制台绑定新版本。
控制台解除旧版本的绑定。
使用文档预览。
步骤一:在控制台绑定新版本
登录OSS管理控制台。
在左侧导航栏,单击Bucket列表,然后单击目标Bucket名称。
在左侧导航栏,选择数据处理。
单击文档处理,然后在弹出绑定页面单击Bucket绑定IMM project按钮。
在绑定智能媒体管理项目对话框的IMM配置区域,根据需要选择以下两种绑定方式中的一种:
创建新的Project:输入Project的名称,系统会自动在存储空间所在的地域创建对应的IMM项目,并将其与当前存储空间绑定。
绑定已有Project:在下拉列表中选择需要绑定至存储空间的IMM项目。
单击文档预览模块,点击创建样式,输入样式名称,点击确定。关于样式的详细介绍,请参见样式。
步骤二:控制台解除旧版本的绑定
新旧版本之间存在不兼容性。解绑后,旧版本IMM项目的文档预览功能将无法继续使用,OSS控制台以及使用SDK调用文档预览接口均会受到影响。因此,请务必谨慎执行解绑操作。
在解除旧版IMM Project的Bucket绑定时,请确保所选的Bucket准确无误,以防止误操作对IMM控制台和OSS控制台的正常使用产生影响。
登录OSS管理控制台。
在左侧导航栏,单击Bucket列表,然后单击目标Bucket名称。
在左侧导航栏,选择数据处理。
在智能媒体界面查看当前Bucket绑定的旧版IMM Project,点击
图标,选择解绑,点击确定。
步骤三:使用文档预览
获取URL链接实现预览
要求使用3.17.4及以上版本的Java SDK,Java SDK的安装请参见安装。
package com.aliyun.oss.demo;
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.GeneratePresignedUrlRequest;
import java.net.URL;
import java.util.Date;
public class Demo {
public static void main(String[] args) throws Throwable {
// 请填写您的自定义域名。例如http://static.example.com。
String endpoint = "http://static.example.com";
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 填写Bucket名称,例如examplebucket。
String bucketName = "examplebucket";
// 填写Object完整路径。如果图片不在Bucket根目录,需携带图片完整路径,例如exampledir/exampleobject.jpg
String objectName = "exampledir/exampleobject.png";
// 填写Bucket所在地域。以华东1(杭州)为例,Region填写为cn-hangzhou。
String region = "cn-hangzhou";
// 创建OSSClient实例。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
// 请注意,设置true开启CNAME选项。
clientBuilderConfiguration.setSupportCname(true);
// 显式声明使用 V4 签名算法
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// 文档处理参数
String style = "doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60";
// 指定签名URL过期时间为3600秒)
Date expiration = new Date(new Date().getTime() + 3600 );
GeneratePresignedUrlRequest req = new GeneratePresignedUrlRequest(bucketName, objectName, HttpMethod.GET);
req.setExpiration(expiration);
req.setProcess(style);
URL signedUrl = ossClient.generatePresignedUrl(req);
System.out.println(signedUrl);
} catch (OSSException oe) {
System.out.println("Caught an OSSException, which means your request made it to OSS, "
+ "but was rejected with an error response for some reason.");
System.out.println("Error Message:" + oe.getErrorMessage());
System.out.println("Error Code:" + oe.getErrorCode());
System.out.println("Request ID:" + oe.getRequestId());
System.out.println("Host ID:" + oe.getHostId());
} catch (ClientException ce) {
System.out.println("Caught an ClientException, which means the client encountered "
+ "a serious internal problem while trying to communicate with OSS, "
+ "such as not being able to access the network.");
System.out.println("Error Message:" + ce.getMessage());
} finally {
if (ossClient != null) {
ossClient.shutdown();
}
}
}
}
要求使用Python SDK 2.18.4及以上版本,Python SDK的安装请参见安装。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# 填写Bucket名称
bucket = 'examplebucket'
# 请填写您的自定义域名。例如https://static.example.com。
endpoint = 'https://static.example.com'
# 填写阿里云通用Region ID
region = 'cn-hangzhou'
# 使用自定义域名初始化bucket,若您使用的是默认域名,则为bucket = oss2.Bucket(auth, endpoint, bucket, region=region)
bucket = oss2.Bucket(auth, endpoint, bucket, is_cname=True, region=region)
# 指定处理文件
key = 'example.docx'
# 指定过期时间,单位秒
expire_time = 3600
# 构建在线预览的处理指令。
image_process = 'doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60'
# 生成签名URL,带上处理参数
url = bucket.sign_url('GET', key, expire_time, params={'x-oss-process': image_process}, slash_safe=True)
# 打印签名URL
print(url)
要求使用Go SDK 3.0.2及以上版本,Go SDK的安装请参见安装OSS Go SDK。
package main
import (
"context"
"flag"
"log"
"time"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)
// 定义全局变量
var (
region string // 存储区域
bucketName string // 存储空间名称
objectName string // 对象名称
)
// init函数用于初始化命令行参数
func init() {
flag.StringVar(®ion, "region", "", "The region in which the bucket is located.")
flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
flag.StringVar(&objectName, "object", "", "The name of the object.")
}
func main() {
// 解析命令行参数
flag.Parse()
// 检查bucket名称是否为空
if len(bucketName) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, bucket name required")
}
// 检查region是否为空
if len(region) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, region required")
}
// 检查object名称是否为空
if len(objectName) == 0 {
flag.PrintDefaults()
log.Fatalf("invalid parameters, object name required")
}
// 加载默认配置并设置凭证提供者和区域
cfg := oss.LoadDefaultConfig().
WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
WithRegion(region).
// 请填写您的自定义域名。例如http://static.example.com。
WithEndpoint("http://static.example.com").
WithUseCName(true)
// 创建OSS客户端
client := oss.NewClient(cfg)
// 生成GetObject的预签名URL
result, err := client.Presign(context.TODO(), &oss.GetObjectRequest{
Bucket: oss.Ptr(bucketName),
Key: oss.Ptr(objectName),
// 设置文档处理参数
Process: oss.Ptr("doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60"),
}, oss.PresignExpires(10*time.Minute))
if err != nil {
log.Fatalf("failed to get object presign %v", err)
}
log.Printf("request method:%v\n", result.Method)
log.Printf("request expiration:%v\n", result.Expiration)
log.Printf("request url:%v\n", result.URL)
if len(result.SignedHeaders) > 0 {
// 当返回结果包含签名头时,使用签名URL发送GET请求时也包含相应的请求头,以免出现不一致,导致请求失败和签名错误
log.Printf("signed headers:\n")
for k, v := range result.SignedHeaders {
log.Printf("%v: %v\n", k, v)
}
}
}
要求使用Node.js SDK 8.0及以上版本,Node.js SDK的安装请参见安装。
const OSS = require("ali-oss");
// 定义一个生成签名 URL 的函数
async function generateSignatureUrl(fileName) {
// 获取签名URL
const client = await new OSS({
// 请填写您的自定义域名。例如http://static.example.com。
endpoint: 'http://static.example.com',
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
bucket: 'examplebucket',
// 填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
region: 'oss-cn-hangzhou',
authorizationV4: true,
cname: true
});
// 生成签名URL,并包含文档处理参数
return await client.signatureUrlV4('GET', 3600, {
headers: {}, // 请根据实际发送的请求头设置此处的请求头
queries: {
"x-oss-process": "doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60" // 添加文档处理参数
}
}, fileName);
}
// 调用函数并传入文件名
generateSignatureUrl('yourFileName').then(url => {
console.log('Generated Signature URL:', url);
}).catch(err => {
console.error('Error generating signature URL:', err);
});
要求使用PHP SDK 2.7.0及以上版本,PHP SDK的安装请参见安装。
<?php
if (is_file(__DIR__ . '/../autoload.php'))
require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
require_once __DIR__ . '/../vendor/autoload.php';
}
use OSS\OssClient;
use OSS\Core\OssException;
use OSS\Http\RequestCore;
use OSS\Http\ResponseCore;
use OSS\Credentials\EnvironmentVariableCredentialsProvider;
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
$provider = new EnvironmentVariableCredentialsProvider();
//请填写您的自定义域名。例如http://static.example.com。
$endpoint = "http://static.example.com";
// 填写Bucket名称,例如examplebucket。
$bucket= "examplebucket";
// 如果文档位于Bucket根目录,则直接填写文档名称。如果文档不在Bucket根目录,需携带文档完整路径,例如exampledir/example.docx。
$key = 'example.docx';
$config = array(
"provider" => $provider,
"endpoint" => $endpoint,
"signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
"cname" => true,
"region"=> "cn-hangzhou"
);
$ossClient = new OssClient($config);
// 生成一个带图片处理参数的签名的URL,有效期是3600秒,可以直接使用浏览器访问。
$timeout = 3600;
$options = array(
// 构建在线预览的处理指令。
OssClient::OSS_PROCESS => "doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60");
$signedUrl = $ossClient->signUrl($bucket, $object, $timeout, "GET", $options);
print("rtmp url: \n" . $signedUrl);
生成的签名URL示例如下:
http://static.example.com/example.docx?x-oss-process=doc%2Fpreview%2Cexport_1%2Cprint_1%2Fwatermark%2Ctext_5YaF6YOo6LWE5paZ%2Csize_30%2Ct_60&x-oss-date=20250122T020741Z&x-oss-expires=3600&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI********************%2F20250122%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-signature=514ed93accdb80921c4b2897c6147fdb1599308c6457f68ee0ac2f771c7d0312
复制生成的URL并粘贴到浏览器地址栏,按回车键即可预览WebOffice文档。
详细参数说明请参见WebOffice在线预览。
相关API
以上操作方式底层基于API实现,如果您的程序自定义要求较高,您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。关于公共请求头Authorization的计算方法,请参见签名版本4(推荐)。
预览信息
预览文档名称:example.docx
预览页面:文档前3页
预览页面水印信息:
水印类型:文字水印
水印文字:内部资料
水印字号:30号字体
水印透明度:60
预览页面权限信息:允许用户复制、导出、打印
处理示例
GET /example.docx?x-oss-process=doc/preview,export_1,print_1/watermark,text_5YaF6YOo6LWE5paZ,size_30,t_60 HTTP/1.1
Host: doc-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: SignatureValue
权限说明
阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限,需要阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予操作权限。
API | Action | 说明 |
API | Action | 说明 |
GetObject |
| 下载Object。 |
| 下载Object时,如果通过versionId指定了Object的版本,则需要授予此操作的权限。 | |
| 下载Object时,如果Object的元数据包含X-Oss-Server-Side-Encryption: KMS,则需要此操作的权限。 |
API | Action | 说明 |
API | Action | 说明 |
无 |
| 通过OSS使用IMM进行数据处理的权限。 |
API | Action | 说明 |
API | Action | 说明 |
GenerateWebofficeToken |
| 用于获取Weboffice凭证。 |
RefreshWebofficeToken |
| 用于刷新Weboffice凭证。 |
计费说明
在文档预览过程中,由于调用了 IMM 服务,会同时在 OSS 和 IMM 两侧产生计费项。具体说明如下:
OSS 侧: 将产生以下计费项,详细定价请参见OSS产品定价:
API
计费项
说明
API
计费项
说明
GetObject
GET 类型请求
根据成功的请求次数计算请求费用。
外网流出流量费用
如果是通过外网Endpoint(示例值oss-cn-hangzhou.aliyuncs.com)或者传输加速Endpoint(示例值oss-accelerate.aliyuncs.com)调用GetObject接口时,会产生外网流出流量费用,根据数据容量大小计费。
低频访问数据取回容量
如果取回的数据是低频访问数据,会产生低频访问数据取回容量的费用,按数据取回量计费。
归档直读数据取回容量
如果读取的是归档的Object且Bucket开启了归档直读,会产生归档直读数据取回容量费用,根据取回的数据容量大小计费。
传输加速
如果开启了传输加速功能且使用传输加速域名访问您的Bucket会产生传输加速费用,根据数据容量大小计费。
IMM 侧: 将产生以下计费项,详细定价请参见IMM计费项:
API
计费项
说明
API
计费项
说明
GenerateWebofficeToken
DocumentWebofficePreview
文档预览功能会产生文档处理费用。
截至2023年12月1日之前创建的在线预览项目将根据文档的打开次数进行收费,而2023年12月1日及之后创建的项目则将按照API接口的调用次数计费。
RefreshWebofficeToken
新旧版本下同一使用场景计费对比
- 本页导读
- 背景信息
- 前提条件
- 如何迁移
- 步骤一:在控制台绑定新版本
- 步骤二:控制台解除旧版本的绑定
- 步骤三:使用文档预览
- 相关API
- 预览信息
- 处理示例
- 权限说明
- 计费说明
- 新旧版本下同一使用场景计费对比