Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Visualização de vídeos

Última atualização: Aug 13, 2026

A visualização de vídeo permite que os usuários assistam ou ouçam conteúdos, como vídeos e áudios, por um tempo limitado. Esse recurso é comum em serviços pagos, como cursos e minisséries. Este tópico descreve como ativar a visualização de vídeo no ApsaraVideo VOD e obter uma URL de visualização.

Como funciona

O Alibaba Cloud ApsaraVideo VOD (VOD) oferece o recurso de visualização. Você pode obter uma URL de visualização definindo uma duração ao chamar a operação da API GetPlayInfo no servidor ou construindo manualmente uma URL assinada com as informações de visualização.

Importante

Se a duração de visualização especificada exceder a duração total do vídeo original, os usuários poderão reproduzir o vídeo inteiro usando a URL de visualização retornada pelo ApsaraVideo VOD.

O recurso de visualização de vídeo do ApsaraVideo VOD baseia-se no Alibaba Cloud CDN. O princípio básico é o seguinte: o player envia uma solicitação contendo uma URL de visualização (um nome de domínio acelerado por CDN) com a duração especificada. A cloud autentica a URL de visualização. Se a autenticação for bem-sucedida, o sistema retorna o conteúdo do arquivo especificado. Caso contrário, o acesso é negado e um erro 403 é retornado. A figura a seguir mostra o fluxo de trabalho de visualização de vídeo.

流程提示

  1. Configure um nome de domínio acelerado por CDN e ative o recurso de visualização de vídeo.

    Importante

    Antes de usar o recurso de visualização, configure um nome de domínio e ative o recurso. Para mais informações, consulte Enable the preview feature.

  2. O player envia uma solicitação de visualização para o ApsaraVideo VOD.

  3. O ApsaraVideo VOD gera uma URL de visualização com base na configuração do nome de domínio e na duração especificada na solicitação.

    Nota

    Chame uma operação de API no servidor para gerar uma URL de visualização ou construa-a manualmente. Para mais informações, consulte Call an API operation to obtain a preview URL ou Manually construct a preview URL.

  4. O player envia uma solicitação ao CDN para reproduzir o vídeo de visualização.

Limites

  • O recurso de visualização de vídeo suporta os formatos de arquivo MP4 e HLS. Para vídeos MP4, os metadados devem estar no cabeçalho do arquivo. Vídeos MP4 com metadados no final do arquivo não são suportados. Ao usar o ApsaraVideo VOD para transcodificar um vídeo para o formato de contêiner MP4, os metadados são colocados no cabeçalho do arquivo.

  • A duração da visualização depende dos keyframes. Por padrão, um keyframe é gerado a cada 10 segundos para arquivos de saída transcodificados pelo ApsaraVideo VOD. Portanto, não use o recurso de visualização para vídeos curtos. Para vídeos longos, defina a duração da visualização como pelo menos 30 segundos.

    Nota

    É possível modificar o intervalo de keyframes nos modelos de transcodificação. Para mais informações, consulte Transcoding Templates.

  • Para arquivos HLS, a precisão da visualização baseia-se na duração de um segmento TS. A duração da visualização é arredondada para cima até o múltiplo mais próximo da duração do segmento TS. Por exemplo, se um segmento TS tiver 10 segundos e você definir a duração da visualização como 15 segundos, uma visualização de 20 segundos será retornada.

Ativar o recurso de visualização de vídeo

Antes de chamar uma operação de API ou construir manualmente uma URL de visualização, configure um nome de domínio e ative o recurso de visualização de vídeo. Siga estas etapas:

  1. Configure um nome de domínio acelerado por CDN. Para mais informações, consulte Add an accelerated domain name.

    Importante

    O recurso de visualização de vídeo está disponível apenas para nomes de domínio configurados como nomes de domínio acelerados por CDN.

  2. Ative a assinatura de URL para um nome de domínio e também ative o recurso de visualização. Para mais informações, consulte URL signing.

    Importante

    Se o recurso de visualização de vídeo estiver desativado para um nome de domínio, não será possível incluir parâmetros de visualização nas solicitações ao ApsaraVideo VOD. A URL retornada ficará inacessível. Portanto, ative a opção Support Previewing ao ativar a assinatura de URL.

    Nota

    Para construir manualmente uma URL de visualização, use o parâmetro privateKey para calcular o valor de autenticação. Defina esse parâmetro com o valor da Primary Key ou Secondary Key obtida no console. Anote o valor da chave para uso futuro.

  3. Ative a busca de origem Range e a busca de vídeo para o nome de domínio. Para mais informações, consulte Configure Range origin fetch e Video seeking.

Chamar uma operação de API para obter uma URL de visualização

O ApsaraVideo VOD fornece uma operação de API para obter URLs de reprodução de vídeo. Para mais informações sobre essa operação, consulte Obtain audio and video playback URLs. Integre um sdk do lado do servidor e use-o para chamar essa operação e obter uma URL de visualização. Para obter a URL de visualização, siga estas etapas:

Importante

Antes de chamar esta operação, certifique-se de que o recurso de visualização esteja ativado. Para mais informações, consulte Enable the preview feature.

  1. Integre o sdk apropriado do lado do servidor. Para mais informações, consulte Quick Start for ApsaraVideo VOD SDKs.

  2. Chame a operação de API Get audio and video playback URL usando o sdk. Ao chamar a operação de API, defina o parâmetro PreviewTime dentro do parâmetro PlayConfig para especificar a duração da visualização. O servidor retorna uma URL de visualização com base na duração especificada. Para mais informações sobre o parâmetro PlayConfig, consulte PlayConfig.

Clique em para visualizar o código de exemplo para obter uma URL de visualização (Java)

Nota
  • Para códigos de exemplo em outras linguagens, consulte OpenAPI.

  • Obtenha um par de AccessKey para concluir a verificação de identidade e poder chamar operações de API do ApsaraVideo VOD. Para mais informações sobre como obter um par de AccessKey, consulte Create an AccessKey pair.


import com.alibaba.fastjson.JSONObject;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.vod.model.v20170321.GetPlayInfoRequest;
import com.aliyuncs.vod.model.v20170321.GetPlayInfoResponse;

/**
 * @date 2021/12/30
 */
public class VodPreviewTest {
    public static void main(String[] args) throws ClientException {
        // Specify the region where ApsaraVideo VOD is activated. For more information, see ApsaraVideo VOD regions.
        String regionId = "cn-shanghai";
        // An AccessKey pair of an Alibaba Cloud account has permissions to call all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M.
        // We strongly recommend that you do not hard-code the AccessKey ID and AccessKey secret in your project code. Otherwise, the AccessKey pair may be leaked and the security of all resources in your account may be compromised.
        // In this example, the AccessKey pair is obtained from environment variables. Before you run the sample code, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
        // Your AccessKey ID.
        String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        // Your AccessKey secret.
        String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        // The video ID. Example: 533606af570e4db4961248d0978b****. If you upload a video in the ApsaraVideo VOD console, you can log on to the console and choose Media Library > Audio/Video to view the video ID. If you upload a video by calling the CreateUploadVideo operation, the value of the VideoId parameter in the response is the video ID.
        String videoId = "<your videoId>";
        DefaultAcsClient client = InitVodClient(regionId, accessKeyId, accessKeySecret);
        GetPlayInfoResponse response = null;
        try {
            response = getPlayInfo(client, videoId);
        } catch (Exception e) {
            e.printStackTrace();
        }
        System.out.println("response = " + JSONObject.toJSONString(response));

    }

    /**
     * Initialize the client.
     *
     * @param regionId
     * @param accessKeyId
     * @param accessKeySecret
     * @return
     * @throws ClientException
     */
    public static DefaultAcsClient InitVodClient(String regionId, String accessKeyId, String accessKeySecret) throws ClientException {
        DefaultProfile profile = DefaultProfile.getProfile(regionId, accessKeyId, accessKeySecret);
        DefaultAcsClient client = new DefaultAcsClient(profile);
        return client;
    }

    /**
     * Obtain the video playback URL.
     *
     * @param client
     * @param videoId
     * @return
     * @throws Exception
     */
    public static GetPlayInfoResponse getPlayInfo(DefaultAcsClient client, String videoId) throws Exception {
        GetPlayInfoRequest request = new GetPlayInfoRequest();
        request.setVideoId(videoId);
        // The validity period of the URL. Unit: seconds. If you do not set this parameter, the default value 3600 is used.
        request.setAuthTimeout(3600L);
        request.setFormats("mp4");
        JSONObject playConfig = new JSONObject();
        // The preview duration. Unit: seconds. The minimum value is 1.
        playConfig.put("PreviewTime", "30");
        request.setPlayConfig(playConfig.toJSONString());
        return client.getAcsResponse(request);
    }
}
                

Construir manualmente uma URL de visualização

Construa manualmente uma URL assinada que contenha informações de visualização. Siga estas etapas:

Importante

Antes de construir uma URL de visualização, certifique-se de que o recurso de visualização esteja ativado. Para mais informações, consulte Enable the preview feature.

  1. Construa uma URL assinada que contenha os parâmetros de visualização. Diferentemente da construção de uma URL assinada para reprodução completa, inclua o parâmetro de duração da visualização previewTime no cálculo do hash MD5 para a assinatura da URL.

    Cálculo do hash MD5 para uma URL de vídeo completo

    Cálculo do hash MD5 para uma URL de visualização

    MD5(uri-timestamp-rand-uid-PrivateKey)

    MD5(uri-timestamp-rand-uid-PrivateKey-previewTime)

    Nota

    Para mais informações sobre os parâmetros para o cálculo do hash MD5 e como construir manualmente uma URL assinada, consulte Configure URL signing. Se quiser permitir a reprodução completa do vídeo, não inclua o parâmetro previewTime.

  2. Anexe &end= ao final da URL assinada construída. Em seguida, adicione o parâmetro de visualização previewTime após &end= para gerar a URL de visualização completa.

Clique em para visualizar as dependências necessárias para o pacote JAR para construção manual (Java)

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.4</version>
</dependency>

Clique em para visualizar o código de exemplo para construir manualmente uma URL de visualização (Java)

    import java.util.UUID;
    import java.net.URL;
    import org.apache.commons.lang3.StringUtils;
    private String generateRand() {
        return UUID.randomUUID().toString().replaceAll("-", "");
    }
    private String md5(String str) {
        try {
            MessageDigest md5 = MessageDigest.getInstance("MD5");
            md5.update(str.getBytes("UTF-8"));
            return bytesToHex(md5.digest());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    public String genAuthKey(String object, String privateKey, Long expireTime, Long previewTime) {
        String rand = "0";
        String uid = "0";
        if (StringUtils.isBlank(privateKey)) {
            return "";
        }
        rand = generateRand();
        long timestamp = System.currentTimeMillis() / 1000 + (expireTime == null ? 0 : expireTime);
        String authStr = timestamp + "-" + rand + "-" + uid;
        String md5Str = object + "-" + authStr + "-" + privateKey;
        if(previewTime!=0)
            md5Str = md5Str + "-" + previewTime;
        String auth_key = authStr + "-" + this.md5(md5Str);
        return auth_key;
    }

    public void previewTest() throws Exception {
        try {
            String key = "<Your PrivateKey>";// The primary or secondary key that you configured in the console. For more information about how to obtain the key, see Enable the video preview feature.
            String fileUrl = "<Your File URL>";// The file URL. Example: http://example.aliyundoc.com/test/bee21427ca3346848835c1bd786054c5-19bd8528c1d51576cd726cf86471ca0****.mp4
            URL url = new URL(fileUrl);
            String file = url.getFile();
            Long previewTime = 120L;// The preview duration.
            Long expireTime = 1800L;
            String auth_key =genAuthKey(file, key, expireTime, previewTime);
            fileUrl = fileUrl + "?auth_key=" + auth_key;
            if(previewTime != 0)
                fileUrl = fileUrl + "&end=" + previewTime;
            System.out.println(fileUrl);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }