ドキュメントスナップショットとは - Object Storage Service

ドキュメントスナップショット機能を使用すると、Word、Excel、PPT、PDF などのドキュメントファイルをダウンロードすることなく、クラウド上で特定のページのスナップショットを生成できます。この機能は、Web ページの埋め込みやデータバックアップなど、さまざまなシナリオをサポートします。

シナリオ

データバックアップと回復: Object Storage Service (OSS) バケット内のドキュメントのスナップショットを定期的に作成して、データをバックアップできます。
キー情報の抽出: ドキュメントスナップショットを使用して特定のページをキャプチャし、キー情報をすばやく抽出できます。

この機能の使用方法

前提条件

Object Storage Service (OSS) では、バケットを作成し、処理するドキュメントをバケットにアップロードし、Intelligent Media Management (IMM) プロジェクトをバケットにアタッチする必要があります。IMM プロジェクトは、バケットと同じリージョンにある必要があります。

ドキュメントスナップショット

SDK を使用してドキュメントスナップショット API を呼び出して処理できます。

Java

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 {
        // 中国 (杭州) リージョンを例として使用します。エンドポイントを実際のリージョンに設定します。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 環境変数からアクセス資格情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // バケット名を指定します (例: examplebucket)。
        String bucketName = "examplebucket";
        // オブジェクトの完全なパスを指定します。ドキュメントがバケットのルートディレクトリにない場合は、完全なパス (例: exampledir/demo.docx) を含める必要があります。
        String objectName = "demo.docx";
        // バケットが配置されているリージョンを指定します。中国 (杭州) リージョンを例として使用します。リージョンを cn-hangzhou に設定します。
        String region = "cn-hangzhou";

        // OSSClient インスタンスを作成します。
        // OSSClient インスタンスが不要になったら、shutdown メソッドを呼び出してリソースを解放します。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // ドキュメントスナップショット処理命令をビルドして、ドキュメントの 2 ページ目のスナップショットを取得します。
            String style = "doc/snapshot,target_jpg,source_docx,page_2";
            // 署名付き URL の有効期限を 3,600 秒に設定します。
            Date expiration = new Date(new Date().getTime() + 3600 * 1000L);
            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

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 環境変数からアクセス資格情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# バケット名を指定します。
bucket = 'examplebucket'

# バケットが配置されているリージョンのエンドポイントを指定します。中国 (杭州) リージョンを例として使用します。
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'

# 汎用 Alibaba Cloud リージョン ID を指定します。
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, bucket, region=region)

# ソースドキュメント名を指定します。ドキュメントがバケットのルートディレクトリにない場合は、完全なパス (例: exampledir/demo.docx) を含める必要があります。
key = 'demo.docx'

# 有効期限を秒単位で指定します。
expire_time = 3600

# ドキュメントスナップショット処理命令をビルドして、ドキュメントの 2 ページ目のスナップショットを取得します。
process = 'doc/snapshot,target_jpg,source_docx,page_2 '

# イメージ処理パラメーターを使用して署名付き URL を生成します。
url = bucket.sign_url('GET', key, expire_time, params={'x-oss-process': process}, slash_safe=True)

# 署名付き URL を出力します。
print(url)

Go

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func HandleError(err error) {
	fmt.Println("Error:", err)
	os.Exit(-1)
}

func main() {
	// 環境変数からアクセス資格情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// OSSClient インスタンスを作成します。
	// yourEndpoint をバケットのエンドポイントに設定します。中国 (杭州) リージョンを例として使用します。エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。必要に応じて他のリージョンを設定します。
	// yourRegion をバケットが配置されているリージョンに設定します。中国 (杭州) リージョンを例として使用します。リージョンを cn-hangzhou に設定します。必要に応じて他のリージョンを設定します。
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// 署名バージョンを設定します。
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		HandleError(err)
	}

	// ドキュメントが保存されているバケットの名前を指定します (例: examplebucket)。
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		HandleError(err)
	}
	// ドキュメント名を指定します。ドキュメントがバケットのルートディレクトリにない場合は、完全なパス (例: exampledir/demo.docx) を含める必要があります。
	ossObjectName := "demo.docx"
	// 署名付き URL を生成し、有効期限を 3,600 秒に設定します。(最大有効期間は 32,400 秒です。)
	signedURL, err := bucket.SignURL(ossObjectName, oss.HTTPGet, 3600, oss.Process("doc/snapshot,target_jpg,source_docx,page_2"))
	if err != nil {
		HandleError(err)
	} else {
		fmt.Println(signedURL)
	}
}

Node.js

const OSS = require("ali-oss");

// 署名付き URL を生成する関数を定義します。
async function generateSignatureUrl(fileName) {
  // 署名付き URL を取得します。
  const client = await new OSS({
      // 環境変数からアクセス資格情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      bucket: 'examplebucket',
      // yourregion をバケットが配置されているリージョンに設定します。中国 (杭州) リージョンを例として使用します。リージョンを oss-cn-hangzhou に設定します。
      region: 'oss-cn-hangzhou',
      // secure を true に設定して HTTPS を使用し、ブラウザが生成されたダウンロードリンクをブロックしないようにします。
      secure: true,
      authorizationV4: true
  });

  return await client.signatureUrlV4('GET', 3600, {
      headers: {}, // 実際に送信するリクエストに基づいてリクエストヘッダーを設定します。
      queries: {
        "x-oss-process": "doc/snapshot,target_jpg,source_docx,page_1" // ドキュメントスナップショット処理命令をビルドして、ドキュメントの 1 ページ目のスナップショットを取得します。
    }
  }, fileName);
}
// 関数を呼び出し、ファイル名を渡します。
generateSignatureUrl('yourFileName').then(url => {
  console.log('Generated Signature URL:', url);
}).catch(err => {
  console.error('Error generating signature URL:', err);
});

PHP

<?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\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;

// 環境変数からアクセス資格情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
$provider = new EnvironmentVariableCredentialsProvider();
// yourEndpoint をバケットが配置されているリージョンのエンドポイントに設定します。中国 (杭州) リージョンを例として使用します。エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。
$endpoint = "yourEndpoint";
// yourRegion をバケットが配置されているリージョンに設定します。中国 (杭州) リージョンを例として使用します。リージョンを cn-hangzhou に設定します。必要に応じて他のリージョンを設定します。
$region = "yourRegion";
// バケット名を指定します (例: examplebucket)。
$bucket= "examplebucket";
// オブジェクトの完全なパスを指定します (例: exampledir/demo.docx)。オブジェクトの完全なパスにバケット名を含めることはできません。
$object = "exampledir/demo.docx";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> $region
    );
    $ossClient = new OssClient($config);

// イメージ処理パラメーターを使用して署名付き URL を生成します。URL は 3,600 秒間有効で、ブラウザで直接アクセスできます。
$timeout = 3600;

$options = array(
    // ドキュメントスナップショット処理命令をビルドして、ドキュメントの 1 ページ目のスナップショットを取得します。
    OssClient::OSS_PROCESS => "doc/snapshot,target_jpg,source_docx,page_1");

$signedUrl = $ossClient->signUrl($bucket, $object, $timeout, "GET", $options);
print("Signed URL: \n" . $signedUrl);

以下は、生成された署名付き URL の例です。

https://examplebucket.oss-cn-hangzhou.aliyuncs.com/demo.docx?x-oss-process=doc%2Fsnapshot%2Ctarget_jpg%2Csource_docx%2Cpage_1&x-oss-date=20250225T023122Z&x-oss-expires=3600&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI********************%2F20250225%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-signature=c6620caa4dc160e5a70ee96b5bae08464edf7a41bb6d47432eda65474f68f26a

生成された URL をコピーしてブラウザのアドレスバーに貼り付けると、指定したドキュメントスナップショットを表示できます。

パラメーター

操作: doc/snapshot

次の表にパラメーターを示します。

パラメーター	タイプ	必須	説明
target	文字列	いいえ	イメージのターゲットフォーマット。有効な値: png (デフォルト) jpg
source	文字列	いいえ	ソースドキュメントのファイル形式。デフォルトでは、オブジェクト名のファイル拡張子が使用されます。有効な値: pdf xlsx xls docx doc pptx ppt 説明このパラメーターを指定せず、オブジェクトにファイル拡張子がない場合、エラーが返されます。
page	int	いいえ	ドキュメントのページ番号。デフォルト値は 1 で、最初のページを示します。最大値は 2000 です。

権限

Alibaba Cloud アカウントは、デフォルトで完全な権限を持っています。デフォルトでは、Alibaba Cloud アカウント下の Resource Access Management (RAM) ユーザーまたは RAM ロールには権限がありません。Alibaba Cloud アカウントまたは管理者は、RAM ポリシーまたはバケットポリシーを使用して権限を付与する必要があります。

API	操作	定義
GetObject	`oss:GetObject`	オブジェクトをダウンロードします。
	`oss:GetObjectVersion`	オブジェクトをダウンロードする際に、versionId を通じてオブジェクトのバージョンを指定する場合、この権限が必要です。
	`kms:Decrypt`	オブジェクトをダウンロードする際に、オブジェクトのメタデータに X-Oss-Server-Side-Encryption: KMS が含まれている場合、この権限が必要です。

API	操作	定義
なし	`oss:ProcessImm`	OSS で IMM のデータ処理機能を使用することを許可します。

API	操作	定義
CreateOfficeConversionTask	`imm:CreateOfficeConversionTask`	ドキュメント変換またはスナップショットに IMM を使用する権限。

課金

ドキュメントスナップショットは、以下の課金項目に対して課金されます。課金項目の価格設定の詳細については、「」OSS 料金および「課金項目」をご参照ください。

API	課金項目	説明
GetObject	GET リクエスト	成功したリクエストの数に基づいてリクエスト料金が課金されます。
	インターネット経由のアウトバウンドトラフィック	oss-cn-hangzhou.aliyuncs.com などのパブリックエンドポイント、または oss-accelerate.aliyuncs.com などのアクセラレーションエンドポイントを使用して GetObject 操作を呼び出す場合、データサイズに基づいてインターネット経由のアウトバウンドトラフィックの料金が課金されます。
	IA オブジェクトの取得	IA オブジェクトが取得される場合、取得された IA データのサイズに基づいて IA データ取得料金が課金されます。
	リアルタイムアクセスが有効になっているバケット内のアーカイブオブジェクトの取得	リアルタイムアクセスが有効になっているバケット内のアーカイブオブジェクトを取得する場合、取得されたアーカイブオブジェクトのサイズに基づいてアーカイブデータ取得料金が課金されます。
	転送アクセラレーション料金	転送アクセラレーションを有効にし、アクセラレーションエンドポイントを使用してバケットにアクセスする場合、データサイズに基づいて転送アクセラレーション料金が課金されます。

API	課金項目	説明
CreateOfficeConversionTask	DocumentConvert	成功したリクエストの数に基づいてリクエスト料金が課金されます。

注意

ドキュメントスナップショットは、同期処理 (x-oss-process メソッド) のみをサポートします。

よくある質問

ドキュメントスナップショットのソースドキュメントの最大サイズはどれくらいですか？

ドキュメントスナップショットのソースドキュメントの最大サイズは 20 MB です。

Object Storage Service:ドキュメントスナップショット