Tous les produits
Search
Centre de documentation

ApsaraVideo VOD:Aperçu des vidéos

Dernière mise à jour :Aug 10, 2026

L'aperçu vidéo permet aux utilisateurs de visionner ou d'écouter du contenu (vidéos et fichiers audio) pendant une durée limitée. Cette fonctionnalité est courante pour les services payants, tels que les cours en ligne et les mini-séries. Cette rubrique explique comment activer l'aperçu vidéo pour ApsaraVideo VOD et obtenir une URL d'aperçu.

Fonctionnement

ApsaraVideo VOD (VOD) d'Alibaba Cloud propose la fonctionnalité d'aperçu. Vous pouvez obtenir une URL d'aperçu en définissant une durée d'aperçu lors de l'appel à l'opération API côté serveur GetPlayInfo, ou en construisant manuellement une URL signée contenant les informations d'aperçu.

Important

Si la durée d'aperçu spécifiée dépasse la durée totale de la vidéo d'origine, les utilisateurs peuvent lire l'intégralité de la vidéo via l'URL d'aperçu renvoyée par ApsaraVideo VOD.

La fonctionnalité d'aperçu vidéo d'ApsaraVideo VOD s'appuie sur Alibaba Cloud CDN. Le principe de base est le suivant : le lecteur envoie une requête contenant une URL d'aperçu (un nom de domaine accéléré par CDN) avec la durée d'aperçu spécifiée. Le service cloud authentifie l'URL d'aperçu. Si l'authentification réussit, le contenu du fichier spécifié est renvoyé. Sinon, l'accès est refusé et une erreur 403 est renvoyée. La figure suivante illustre le flux de travail de l'aperçu vidéo.

流程提示

  1. Configurez un nom de domaine accéléré par CDN et activez la fonctionnalité d'aperçu vidéo.

    Important

    Avant d'utiliser la fonctionnalité d'aperçu, vous devez configurer un nom de domaine et activer cette fonctionnalité. Pour plus d'informations, consultez Activer la fonctionnalité d'aperçu.

  2. Votre lecteur envoie une requête d'aperçu à ApsaraVideo VOD.

  3. ApsaraVideo VOD génère une URL d'aperçu en fonction de la configuration du nom de domaine et de la durée d'aperçu spécifiée dans la requête.

    Remarque

    Vous pouvez appeler une opération API côté serveur pour générer une URL d'aperçu ou construire une URL d'aperçu manuellement. Pour plus d'informations, consultez Appeler une opération API pour obtenir une URL d'aperçu ou Construire manuellement une URL d'aperçu.

  4. Votre lecteur envoie une requête à CDN pour lire la vidéo d'aperçu.

Limites

  • La fonctionnalité d'aperçu vidéo prend en charge les formats de fichier MP4 et HLS. Pour les vidéos MP4, les métadonnées doivent se trouver dans l'en-tête du fichier. Les vidéos MP4 dont les métadonnées se trouvent à la fin du fichier ne sont pas prises en charge. Lorsque vous utilisez ApsaraVideo VOD pour transcoder une vidéo au format conteneur MP4, les métadonnées sont placées dans l'en-tête du fichier.

  • La durée d'aperçu dépend des images clés. Par défaut, une image clé est générée toutes les 10 secondes pour les fichiers de sortie transcodés par ApsaraVideo VOD. Nous vous recommandons donc de ne pas utiliser la fonctionnalité d'aperçu pour les vidéos courtes. Pour les vidéos longues, définissez la durée d'aperçu sur au moins 30 secondes.

    Remarque

    Vous pouvez modifier l'intervalle entre les images clés dans les modèles de transcodage. Pour plus d'informations, consultez Modèles de transcodage.

  • Pour les fichiers HLS, la précision de l'aperçu est basée sur la durée d'un segment TS. La durée d'aperçu est arrondie au multiple supérieur le plus proche de la durée du segment TS. Par exemple, si un segment TS dure 10 secondes et que vous définissez la durée d'aperçu sur 15 secondes, un aperçu de 20 secondes est renvoyé.

Activer la fonctionnalité d'aperçu vidéo

Avant d'appeler une opération API ou de construire manuellement une URL pour obtenir une URL d'aperçu, vous devez configurer un nom de domaine et activer la fonctionnalité d'aperçu vidéo. Suivez ces étapes :

  1. Configurez un nom de domaine accéléré par CDN. Pour plus d'informations, consultez Ajouter un nom de domaine accéléré.

    Important

    La fonctionnalité d'aperçu vidéo est disponible uniquement pour les noms de domaine configurés comme noms de domaine accélérés par CDN.

  2. Activez la signature d'URL pour un nom de domaine et activez la fonctionnalité d'aperçu. Pour plus d'informations, consultez Signature d'URL.

    Important

    Si la fonctionnalité d'aperçu vidéo est désactivée pour un nom de domaine, vous ne pouvez pas inclure de paramètres d'aperçu dans les requêtes adressées à ApsaraVideo VOD. L'URL renvoyée sera inaccessible. Par conséquent, vous devez activer le commutateur Support Previewing lorsque vous activez la signature d'URL.

    La figure suivante montre l'interface de la console pour activer la fonctionnalité d'aperçu vidéo.

    Remarque

    Pour construire manuellement une URL d'aperçu, vous devez utiliser le paramètre privateKey pour calculer la valeur d'authentification. Définissez ce paramètre sur la valeur de la Primary Key ou de la Secondary Key obtenue depuis la console. Conservez la valeur de la clé pour une utilisation future.

    开启试看功能

  3. Activez la récupération d'origine par plage (Range origin fetch) et la recherche vidéo pour le nom de domaine. Pour plus d'informations, consultez Configurer la récupération d'origine par plage et Recherche vidéo.

Appeler une opération API pour obtenir une URL d'aperçu

ApsaraVideo VOD fournit une opération API pour obtenir des URL de lecture vidéo. Pour plus d'informations sur l'opération API, consultez Obtenir des URL de lecture audio et vidéo. Vous pouvez intégrer un SDK côté serveur et l'utiliser pour appeler cette opération afin d'obtenir une URL d'aperçu. Pour obtenir l'URL d'aperçu, suivez ces étapes :

Important

Avant d'appeler cette opération, assurez-vous que la fonctionnalité d'aperçu est activée. Pour plus d'informations, consultez Activer la fonctionnalité d'aperçu.

  1. Intégrez le SDK côté serveur approprié. Pour plus d'informations, consultez Démarrage rapide des SDK ApsaraVideo VOD.

  2. Appelez l'opération API Obtenir l'URL de lecture audio et vidéo à l'aide du SDK. Lors de l'appel à l'opération API, définissez le paramètre PreviewTime au sein du paramètre PlayConfig pour spécifier la durée d'aperçu. Le serveur renvoie une URL d'aperçu en fonction de la durée spécifiée. Pour plus d'informations sur le paramètre PlayConfig, consultez PlayConfig.

Cliquez pour afficher l'exemple de code pour obtenir une URL d'aperçu (Java)

Remarque
  • Pour des exemples de code dans d'autres langages, consultez OpenAPI.

  • Obtenez une paire AccessKey pour effectuer la vérification d'identité afin de pouvoir appeler les opérations API d'ApsaraVideo VOD. Pour plus d'informations sur l'obtention d'une paire AccessKey, consultez Créer une paire 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);
    }
}
                

Construire manuellement une URL d'aperçu

Vous pouvez construire manuellement une URL signée contenant les informations d'aperçu. Suivez ces étapes :

Important

Avant de construire une URL d'aperçu, assurez-vous que la fonctionnalité d'aperçu est activée. Pour plus d'informations, consultez Activer la fonctionnalité d'aperçu.

  1. Construisez une URL signée contenant les paramètres d'aperçu. Contrairement à la construction d'une URL signée pour la lecture complète, vous devez inclure le paramètre de durée d'aperçu previewTime dans le calcul du hachage MD5 pour la signature d'URL.

    Calcul du hachage MD5 pour une URL de vidéo complète

    Calcul du hachage MD5 pour une URL d'aperçu

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

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

    Remarque

    Pour plus d'informations sur les paramètres pour le calcul du hachage MD5 et sur la construction manuelle d'une URL signée, consultez Configurer la signature d'URL. Si vous souhaitez autoriser la lecture complète de la vidéo, n'incluez pas le paramètre previewTime.

  2. Ajoutez &end= à la fin de l'URL signée construite. Ensuite, ajoutez le paramètre d'aperçu previewTime après &end= pour générer l'URL d'aperçu complète.

Cliquez pour afficher les dépendances requises pour le package JAR pour la construction manuelle (Java)

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

Cliquez pour afficher l'exemple de code pour construire manuellement une URL d'aperçu (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();
        }
    }