Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Visualizar vídeos

Última atualização: Jun 27, 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 do lado do servidor GetPlayInfo 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 nuvem 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 obter mais informações, consulte Ativar o recurso de visualização.

  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 do lado do servidor para gerar uma url de visualização ou construa-a manualmente. Para obter mais informações, consulte Chamar uma operação de API para obter uma url de visualização ou Construir manualmente uma url de visualização.

  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, recomenda-se não usar 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 obter mais informações, consulte Modelos de Transcodificação.

  • 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 de duração 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 para obter 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 obter mais informações, consulte Adicionar um nome de domínio acelerado.

    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 obter mais informações, consulte Assinatura de URL.

    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 chave Support Previewing ao ativar a assinatura de URL.

    A figura a seguir mostra a interface do console para ativar o recurso de visualização de vídeo.

    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 obter mais informações, consulte Configurar busca de origem Range e Busca de vídeo.

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 obter mais informações sobre a operação de API, consulte Obter URLs de reprodução de áudio e vídeo. 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 obter mais informações, consulte Ativar o recurso de visualização.

  1. Integre o sdk apropriado do lado do servidor. Para obter mais informações, consulte Início Rápido para SDKs do ApsaraVideo VOD.

  2. Chame a operação de API Obter URL de reprodução de áudio e vídeo 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 obter 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 obter mais informações sobre como obter um par de AccessKey, consulte Criar um par de AccessKey.


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 obter mais informações, consulte Ativar o recurso de visualização.

  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 de hash MD5 para uma URL de vídeo completo

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

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

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

    Nota

    Para obter mais informações sobre os parâmetros para o cálculo do hash MD5 e como construir manualmente uma URL assinada, consulte Configurar assinatura de URL. 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();
        }
    }