Apa itu snapshot dokumen - Object Storage Service

Gunakan fitur snapshot dokumen untuk menghasilkan snapshot halaman tertentu dari file Word, Excel, PPT, atau PDF di cloud tanpa perlu mengunduhnya. Fitur ini mendukung berbagai skenario seperti penyematan web dan cadangan data.

Skenario

Cadangan dan pemulihan data: Secara berkala buat snapshot dokumen di bucket Object Storage Service (OSS) Anda untuk cadangan data.
Ekstraksi informasi kunci: Gunakan snapshot dokumen untuk menangkap halaman tertentu guna mengekstrak informasi penting dengan cepat.

Cara menggunakan fitur ini

Prasyarat

Di dalam Object Storage Service (OSS), Anda harus membuat bucket, mengunggah dokumen yang akan diproses ke bucket tersebut, dan menyambungkan proyek Intelligent Media Management (IMM) ke bucket. Proyek IMM harus berada di wilayah yang sama dengan bucket.

Snapshots dokumen

Gunakan SDK untuk memanggil API snapshot dokumen dalam pemrosesan.

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 {
        // Wilayah China (Hangzhou) digunakan sebagai contoh. Atur Endpoint ke wilayah aktual.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket, misalnya, examplebucket.
        String bucketName = "examplebucket";
        // Tentukan jalur lengkap objek. Jika dokumen tidak berada di direktori root bucket, Anda harus menyertakan jalur lengkap, misalnya, exampledir/demo.docx.
        String objectName = "demo.docx";
        // Tentukan wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur wilayah ke cn-hangzhou.
        String region = "cn-hangzhou";

        // Buat instance OSSClient.
        // Saat instance OSSClient tidak lagi diperlukan, panggil metode shutdown untuk melepaskan sumber daya.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Bangun instruksi pemrosesan snapshot dokumen untuk mendapatkan snapshot halaman kedua dokumen.
            String style = "doc/snapshot,target_jpg,source_docx,page_2";
            // Atur waktu kedaluwarsa URL yang ditandatangani menjadi 3.600 detik.
            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("Tangkap OSSException, yang berarti permintaan Anda sampai ke OSS, "
                    + "tetapi ditolak dengan respons kesalahan karena alasan tertentu.");
            System.out.println("Pesan Kesalahan:" + oe.getErrorMessage());
            System.out.println("Kode Kesalahan:" + oe.getErrorCode());
            System.out.println("ID Permintaan:" + oe.getRequestId());
            System.out.println("ID Host:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Tangkap ClientException, yang berarti klien mengalami "
                    + "masalah internal serius saat mencoba berkomunikasi dengan OSS, "
                    + "seperti tidak dapat mengakses jaringan.");
            System.out.println("Pesan Kesalahan:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Python

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

# Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Tentukan nama bucket.
bucket = 'examplebucket'

# Tentukan Endpoint untuk wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh.
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'

# Tentukan ID wilayah umum Alibaba Cloud.
region = 'cn-hangzhou'
bucket = oss2.Bucket(auth, endpoint, bucket, region=region)

# Tentukan nama dokumen sumber. Jika dokumen tidak berada di direktori root bucket, Anda harus menyertakan jalur lengkap, misalnya, exampledir/demo.docx.
key = 'demo.docx'

# Tentukan waktu kedaluwarsa dalam detik.
expire_time = 3600

# Bangun instruksi pemrosesan snapshot dokumen untuk mendapatkan snapshot halaman kedua dokumen.
process = 'doc/snapshot,target_jpg,source_docx,page_2 '

# Hasilkan URL yang ditandatangani dengan parameter pemrosesan gambar.
url = bucket.sign_url('GET', key, expire_time, params={'x-oss-process': process}, slash_safe=True)

# Cetak URL yang ditandatangani.
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() {
	// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// Buat instance OSSClient.
	// Atur yourEndpoint ke Endpoint bucket. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur Endpoint ke https://oss-cn-hangzhou.aliyuncs.com. Atur wilayah lain sesuai kebutuhan.
	// Atur yourRegion ke wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur wilayah ke cn-hangzhou. Atur wilayah lain sesuai kebutuhan.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Atur versi tanda tangan.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		HandleError(err)
	}

	// Tentukan nama bucket tempat dokumen disimpan, misalnya, examplebucket.
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		HandleError(err)
	}
	// Tentukan nama dokumen. Jika dokumen tidak berada di direktori root bucket, Anda harus menyertakan jalur lengkap, misalnya, exampledir/demo.docx.
	ossObjectName := "demo.docx"
	// Hasilkan URL yang ditandatangani dan atur waktu kedaluwarsa menjadi 3.600 detik. (Masa berlaku maksimum adalah 32.400 detik.)
	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");

// Definisikan fungsi untuk menghasilkan URL yang ditandatangani.
async function generateSignatureUrl(fileName) {
  // Dapatkan URL yang ditandatangani.
  const client = await new OSS({
      // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      bucket: 'examplebucket',
      // Atur yourregion ke wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur wilayah ke oss-cn-hangzhou.
      region: 'oss-cn-hangzhou',
      // Atur secure ke true untuk menggunakan HTTPS dan mencegah browser memblokir tautan unduhan yang dihasilkan.
      secure: true,
      authorizationV4: true
  });

  return await client.signatureUrlV4('GET', 3600, {
      headers: {}, // Atur header permintaan berdasarkan permintaan aktual yang Anda kirim.
      queries: {
        "x-oss-process": "doc/snapshot,target_jpg,source_docx,page_1" // Bangun instruksi pemrosesan snapshot dokumen untuk mendapatkan snapshot halaman pertama dokumen.
    }
  }, fileName);
}
// Panggil fungsi dan lewatkan nama file.
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;

// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
$provider = new EnvironmentVariableCredentialsProvider();
// Atur yourEndpoint ke Endpoint untuk wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur Endpoint ke https://oss-cn-hangzhou.aliyuncs.com.
$endpoint = "yourEndpoint";
// Atur yourRegion ke wilayah tempat bucket berada. Wilayah China (Hangzhou) digunakan sebagai contoh. Atur wilayah ke cn-hangzhou. Atur wilayah lain sesuai kebutuhan.
$region = "yourRegion";
// Tentukan nama bucket, misalnya, examplebucket.
$bucket= "examplebucket";
// Tentukan jalur lengkap objek, misalnya, exampledir/demo.docx. Jalur lengkap objek tidak boleh berisi nama bucket.
$object = "exampledir/demo.docx";

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

// Hasilkan URL yang ditandatangani dengan parameter pemrosesan gambar. URL valid selama 3.600 detik dan dapat diakses langsung di browser.
$timeout = 3600;

$options = array(
    // Bangun instruksi pemrosesan snapshot dokumen untuk mendapatkan snapshot halaman pertama dokumen.
    OssClient::OSS_PROCESS => "doc/snapshot,target_jpg,source_docx,page_1");

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

Berikut adalah contoh URL yang ditandatangani yang dihasilkan:

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

Salin URL yang dihasilkan dan tempelkan ke bilah alamat browser Anda untuk melihat snapshot dokumen yang ditentukan.

Parameter

Action: doc/snapshot

Tabel berikut menjelaskan parameter-parameter tersebut.

Parameter	Tipe	Diperlukan	Deskripsi
target	string	Tidak	Format target dari citra. Nilai yang valid: png (default) jpg
source	string	Tidak	Format file dari dokumen sumber. Secara default, ekstensi file dari nama objek digunakan. Nilai yang valid: pdf xlsx xls docx doc pptx ppt Catatan Jika Anda tidak menentukan parameter ini dan objek tidak memiliki ekstensi file, kesalahan akan dikembalikan.
page	int	Tidak	Nomor halaman dokumen. Nilai default adalah 1, yang menunjukkan halaman pertama. Nilai maksimum adalah 2000.

Operasi API terkait

Operasi sebelumnya diimplementasikan menggunakan panggilan API. Jika program Anda memiliki persyaratan kustomisasi tinggi, Anda dapat langsung mengirimkan permintaan REST API. Saat mengirimkan permintaan REST API, Anda harus menulis kode secara manual untuk menghitung tanda tangan. Untuk informasi lebih lanjut tentang cara menghitung header permintaan umum `Authorization`, lihat Signature Version 4 (disarankan).

Dapatkan Snapshot halaman pertama dari example.docx

Metode pemrosesan

Pemrosesan default

Contoh

// Dapatkan Snapshot halaman pertama dari example.docx.
GET /exmaple.docx?x-oss-process=doc/snapshot HTTP/1.1
Host: doc-demo.oss-cn-hangzhou.aliyuncs.com
Date: Jumat, 28 Okt 2022 06:40:10 GMT
Authorization: SignatureValue

Dapatkan Snapshot JPG dari halaman kedua dokumen Word contoh

Metode pemrosesan

target: jpg
source: docx
page: 2

Contoh

// Dapatkan Snapshot JPG dari halaman kedua dokumen Word contoh.
GET /exmaple?x-oss-process=doc/snapshot,target_jpg,source_docx,page_2 HTTP/1.1
Host: doc-demo.oss-cn-hangzhou.aliyuncs.com
Date: Jumat, 28 Okt 2022 06:40:10 GMT
Authorization: SignatureValue

Izin

Akun Alibaba Cloud memiliki izin penuh secara default. Seorang Pengguna Resource Access Management (RAM) atau Peran RAM di bawah Akun Alibaba Cloud tidak memiliki izin apa pun secara default. Administrator harus memberikan izin menggunakan Kebijakan RAM atau kebijakan bucket.

API	Aksi	Definisi
GetObject	`oss:GetObject`	Mengunduh sebuah objek.
	`oss:GetObjectVersion`	Saat mengunduh sebuah objek, jika Anda menentukan versi objek melalui versionId, izin ini diperlukan.
	`kms:Decrypt`	Saat mengunduh sebuah objek, jika metadata objek berisi X-Oss-Server-Side-Encryption: KMS, izin ini diperlukan.

API	Aksi	Definisi
Tidak ada	`oss:ProcessImm`	Mengizinkan penggunaan kemampuan pemrosesan data IMM di OSS.

API	Aksi	Definisi
CreateOfficeConversionTask	`imm:CreateOfficeConversionTask`	Izin untuk menggunakan IMM untuk konversi dokumen atau Snapshot.

Penagihan

Snapshot dokumen dikenakan biaya untuk item yang dapat ditagih berikut ini. Untuk informasi lebih lanjut tentang harga item yang dapat ditagih, lihat OSS Pricing dan Item yang dapat ditagih:

API	Item yang dapat ditagih	Deskripsi
GetObject	Permintaan GET	Anda akan dikenakan biaya permintaan berdasarkan jumlah permintaan yang berhasil.
	Lalu lintas keluar melalui Internet	Jika Anda memanggil operasi GetObject menggunakan titik akhir publik, seperti oss-cn-hangzhou.aliyuncs.com, atau titik akhir percepatan, seperti oss-accelerate.aliyuncs.com, Anda akan dikenakan biaya lalu lintas keluar melalui Internet berdasarkan ukuran data.
	Pengambilan objek IA	Jika objek IA diambil, Anda akan dikenakan biaya pengambilan data IA berdasarkan ukuran data IA yang diambil.
	Pengambilan objek Arsip dalam bucket yang memiliki akses real-time diaktifkan	Jika Anda mengambil objek Arsip dalam bucket yang memiliki akses real-time diaktifkan, Anda akan dikenakan biaya pengambilan data Arsip berdasarkan ukuran objek Arsip yang diambil.
	Biaya akselerasi transfer	Jika Anda mengaktifkan akselerasi transfer dan menggunakan titik akhir percepatan untuk mengakses bucket Anda, Anda akan dikenakan biaya akselerasi transfer berdasarkan ukuran data.

API	Item yang dapat ditagih	Deskripsi
CreateOfficeConversionTask	DocumentConvert	Anda akan dikenakan biaya permintaan berdasarkan jumlah permintaan yang berhasil.

Object Storage Service：Snapshot dokumen

Skenario

Cara menggunakan fitur ini

Prasyarat

Snapshots dokumen

Java

Python

Go

Node.js

PHP

Parameter

Operasi API terkait

Dapatkan Snapshot halaman pertama dari example.docx

Metode pemrosesan

Contoh

Dapatkan Snapshot JPG dari halaman kedua dokumen Word contoh

Metode pemrosesan

Contoh

Izin

Penagihan

Catatan

FAQ

Berapa ukuran maksimum dokumen sumber untuk Snapshot dokumen?