Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Fazer upload de arquivos com o SDK para PHP

Última atualização: Sep 22, 2026

Este tópico apresenta exemplos detalhados de como usar o kit de desenvolvimento de software (SDK) de upload do lado do servidor para PHP para fazer upload de diversos arquivos de mídia para o armazenamento no ApsaraVideo VOD.

Visão geral

Nota

Recomendamos uma arquitetura B/S (Browser/Server) para desenvolvimento em PHP.

O SDK de upload para PHP segue o fluxo geral do SDK do lado do servidor do ApsaraVideo VOD. Para obter mais informações, consulte Upload process. O fluxo básico para usar o SDK de upload para PHP é o seguinte:

  1. Conclua os pré-requisitos. Para obter mais informações, consulte Prerequisites.

  2. Integre o SDK de upload para PHP. Para obter mais informações, consulte Integrate the PHP upload SDK.

  3. Implemente a lógica de upload e configure as informações de upload.

  4. O endpoint padrão do SDK de upload para PHP é cn-shanghai (Shanghai). Para fazer upload de arquivos de mídia para outras regiões, especifique a região ao inicializar AliyunVodUploader. Para obter mais informações sobre os endpoints compatíveis com o ApsaraVideo VOD, consulte Endpoints.

    O exemplo a seguir mostra: defina a região de upload como cn-beijing (Beijing):

    $apiRegionId = 'cn-beijing';  // The destination region for the upload.
    $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret, $apiRegionId);

Pré-requisitos

  • Você ativou o ApsaraVideo VOD. Para obter mais informações, consulte Activate ApsaraVideo VOD.

  • Você configurou as definições do sistema necessárias para o upload, incluindo o caminho de armazenamento na região especificada e as configurações de callback. Para obter mais informações, consulte gerencie storage buckets e Configure callbacks.

  • Você criou um usuário ram para acessar o ApsaraVideo VOD. Para evitar riscos de segurança causados pelo vazamento do par de AccessKey da sua conta alibaba cloud, recomendamos criar um usuário ram e conceder a ele as permissões necessárias para acessar o ApsaraVideo VOD. Em seguida, use o par de AccessKey do usuário ram para acessar o ApsaraVideo VOD. Para obter mais informações, consulte crie a RAM user and grant permissions.

  • Configure as variáveis de ambiente ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET. Para obter mais informações, consulte Configure environment variables on Linux, macOS, and Windows.

    Importante
    • Um par de AccessKey de conta alibaba cloud tem permissões para todas as operações de api. Use o par de AccessKey de um usuário ram para chamar operações de api ou execute tarefas rotineiras de O&M.

    • Não codifique o AccessKey id nem o AccessKey secret diretamente no código do projeto. Em caso de vazamento, todos os recursos da sua conta ficam comprometidos.

  • Opcional. Para acessar o ApsaraVideo VOD com o Security Token service (STS), crie uma função para o usuário ram e conceda à função as permissões necessárias para acessar o ApsaraVideo VOD. Para obter mais informações, consulte Obtain an STS token.

Integrar o SDK de upload para PHP

  1. baixe o SDK e a demonstração.

  2. Descompacte VodUploadSDK-PHP_1.0.3.zip e copie a pasta voduploadsdk do diretório VodUploadSDK-PHP_1.0.3 para o seu projeto.

Estrutura de diretórios do SDK de upload para PHP

Caminho: VodUploadSDK-PHP_1.0.3/voduploadsdk/uploader

  • UploadVideoRequest.php

    Diretório

    Descrição

    UploadVideoRequest

    Classe de solicitação para upload de vídeos. Para obter mais informações sobre os campos, consulte CreateUploadVideo.

  • UploadImageRequest.php

    Diretório

    Descrição

    UploadImageRequest

    Classe de solicitação para upload de imagens. Para obter mais informações sobre os campos, consulte CreateUploadImage.

  • UploadAttachedMediaRequest.php

    Diretório

    Descrição

    UploadAttachedMediaRequest

    Classe de solicitação para upload de ativos de mídia auxiliares. Para obter mais informações sobre os campos, consulte CreateUploadAttachedMedia.

  • AliyunVodUploader.php

    Diretório

    Descrição

    __construct

    Defina a AccessKey usada nos uploads, o centro do ApsaraVideo VOD e o endpoint. Para obter mais informações, consulte AccessKey e ApsaraVideo VOD region ids.

    uploadLocalVideo

    Interface para upload de vídeos locais.

    uploadWebVideo

    Interface para upload de vídeos da web.

    uploadLocalImage

    Faz upload de imagens locais.

    uploadWebImage

    Faz upload de imagens da web.

    uploadLocalAttachedMedia

    Faz upload de ativos de mídia auxiliares locais.

    uploadWebAttachedMedia

    Faz upload de ativos de mídia auxiliares da web.

    uploadLocalM3u8

    Faz upload de arquivos M3U8 locais.

    uploadWebM3u8

    Faz upload de arquivos M3U8 da web.

    parseM3u8File

    Analisa um manifesto M3U8 para obter uma lista de endereços de shards.

    setEcsRegionId

    Define a região em que o script de upload está implantado em uma instância ECS, quando aplicável. Se a região for igual à região de armazenamento do ApsaraVideo VOD, o SDK ativará automaticamente o upload pela rede interna.

    setEnableSSL

    Especifica se o SDK deve ativar SSL (usar HTTPS para solicitações de rede). Por padrão, o recurso fica desativado para evitar problemas quando as extensões relacionadas não estão instaladas ou estão configuradas incorretamente.

    uploadProgressCallback

    Função de callback para o progresso do upload. Você pode reescrever esta função. Para ver a assinatura do método e um exemplo de substituição, consulte as informações a seguir.

    Assinatura do método uploadProgressCallback

    public function uploadProgressCallback($mediaId, $consumedBytes, $totalBytes)
    • $mediaId: id da mídia.

    • $consumedBytes: número de bytes enviados até o momento.

    • $totalBytes: tamanho total do arquivo em bytes.

    Para calcular a porcentagem de progresso do upload, use 100 * ($consumedBytes / $totalBytes). Verifique se $totalBytes é maior que 0 antes da divisão para evitar divisão por zero.

    Para exibir um progresso de upload personalizado, estenda AliyunVodUploader e substitua este método. Veja o exemplo a seguir:

    class MyAliyunVodUploader extends AliyunVodUploader {
        public function uploadProgressCallback($mediaId, $consumedBytes, $totalBytes) {
            if ($totalBytes > 0) {
                $rate = 100 * (floatval($consumedBytes) / floatval($totalBytes));
            } else {
                $rate = 0;
            }
            echo round($rate, 1) . "%\n";
            flush();
        }
    }
  • AliyunVodUtils.php

    Diretório

    Descrição

    AliyunVodUtils

    Classe utilitária que fornece funções estáticas, como funções para truncar strings, obter extensões de arquivo e obter nomes de arquivo.

    AliyunVodLog

    Classe de log para impressão simples. logSwitch é a opção que ativa ou desativa logs.

    AliyunVodDownloader

    Baixa arquivos da web.

    AliyunVodReportUpload

    Informa o progresso do upload.

    AliyunVodError

    Defina códigos de erro.

Caminho: VodUploadSDK-PHP_1.0.3/voduploadsdk

  • aliyun-php-sdk-core: dependência que fornece a classe base para o SDK de upload. Ela encapsula assinatura de api do alibaba cloud, solicitações HTTP e outras funcionalidades principais.

  • aliyun-php-sdk-vod: SDK de api do lado do servidor para o ApsaraVideo VOD. Ele encapsula solicitações para api do ApsaraVideo VOD.

  • aliyun-php-sdk-oss: dependência que fornece a classe OSS para o SDK de upload. Ela encapsula operações de upload do OSS e outras funções relacionadas.

Caminho: VodUploadSDK-PHP_1.0.3/samples

  • uploadVideo.php: código de exemplo para upload de vídeos.

  • uploadImage.php: código de exemplo para upload de imagens.

  • uploadAttachedMedia.php: código de exemplo para upload de ativos de mídia auxiliares.

Cenário 1: fazer upload de arquivos de áudio e vídeo

Arquivos de áudio e vídeo padrão

Você pode fazer upload dos seguintes tipos de arquivos de áudio e vídeo:

  • O SDK envia arquivos locais por upload multipart. Um único arquivo pode ter até 48,8 TB. O upload retomável não é compatível. Para obter mais informações, consulte a função testUploadLocalVideo.

  • Também é possível fazer upload de arquivos da web especificando uma url de arquivo. Um único arquivo pode ter até 48,8 TB. Nesse método, o arquivo da web é baixado para um disco local antes do upload. Verifique se o disco local tem espaço suficiente. Para obter mais informações, consulte a função testUploadWebVideo.

clique em e visualize o código de exemplo

<?php
/**
 * Created by Aliyun ApsaraVideo VOD.
 */
require_once dirname(__DIR__) . DIRECTORY_SEPARATOR . 'voduploadsdk' . DIRECTORY_SEPARATOR . 'Autoloader.php';
date_default_timezone_set('PRC');
// Test uploading a local video.
function testUploadLocalVideo($accessKeyId, $accessKeySecret, $filePath)
{
    try {
        $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
        $uploadVideoRequest = new UploadVideoRequest($filePath, 'testUploadLocalVideo via PHP-SDK');
        // CateId is the media category ID. You can view it on the **Category Management** page under **Configuration Management** > **Media Management** in the ApsaraVideo VOD console, or create one by calling the AddCategory operation. For more information, see [Manage media categories](https://www.alibabacloud.com/help/zh/vod/user-guide/manage-video-categories).
        $uploadVideoRequest->setCateId(<your category ID>);
        // Example CoverURL: http://example.com/example****.jpg
        //$uploadVideoRequest->setCoverURL("<your CoverURL>");
        //$uploadVideoRequest->setTags('test1,test2');
        //$uploadVideoRequest->setStorageLocation('outin-xx.oss-cn-beijing.aliyuncs.com');
        $uploadVideoRequest->setTemplateGroupId('your-template-group-id');
        $userData = array(
            // Example Callback: https://demo.aliyundoc.com/ProcessMessageCallback
            "MessageCallback"=>array("CallbackURL"=>"<your callback URL>"),
            "Extend"=>array("localId"=>"xxx", "test"=>"www")
        );
        $uploadVideoRequest->setUserData(json_encode($userData));
        $res = $uploader->uploadLocalVideo($uploadVideoRequest);
        print_r($res);
    } catch (Exception $e) {
        printf("testUploadLocalVideo Failed, ErrorMessage: %s\n Location: %s %s\n Trace: %s\n",
            $e->getMessage(), $e->getFile(), $e->getLine(), $e->getTraceAsString());
    }
}
// Test uploading a web video.
function testUploadWebVideo($accessKeyId, $accessKeySecret, $fileURL)
{
    try {
        $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
        $uploadVideoRequest = new UploadVideoRequest($fileURL, 'testUploadWebVideo via PHP-SDK');
        $res = $uploader->uploadWebVideo($uploadVideoRequest);
        print_r($res);
    } catch (Exception $e) {
        printf("testUploadWebVideo Failed, ErrorMessage: %s\n Location: %s %s\n Trace: %s\n",
            $e->getMessage(), $e->getFile(), $e->getLine(), $e->getTraceAsString());
    }
}

####  Run the test code   ####
// The AccessKey pair of an Alibaba Cloud account has permissions to access all APIs. Use the AccessKey pair of a RAM user for API access or daily O&M.
// Do not hard-code the AccessKey ID and AccessKey secret into your project code. This can lead to an AccessKey pair leak and compromise the security of all resources in your account.
// This example shows how to use an AccessKey pair from environment variables to authenticate API access. Before you run the sample code, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');
$accessKeySecret = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');
$localFilePath = '/opt/video/sample.mp4';
// testUploadLocalVideo($accessKeyId, $accessKeySecret, $localFilePath);

// Example webFileURL: http://example-bucket-****.cn-shanghai.aliyuncs.com/b55b904bc612463b812990b7c8cc****/daa30814c0c340cf8199926f78aa****-a0bc05ba62c3e95cc672e88b8281****-ld.mp4?auth_key=1608774986-0-0-c56acd302bea0c331370d8ed6865****
$webFileURL = '<your webFileURL>';
testUploadWebVideo($accessKeyId, $accessKeySecret, $webFileURL);

uploadLocalVideo permite especificar um grupo de modelos de transcodificação durante o upload de um vídeo chamando setTemplateGroupId(). Se você especificar um id de grupo de modelos de transcodificação, o service transcodificará o vídeo automaticamente assim que o upload for concluído, e não será necessário chamar a operação SubmitTranscodeJobs separadamente. Para obter o id do grupo de modelos de transcodificação, acesse a página Configuration Management > Media Processing Configuration > Transcoding Template Groups no console do VOD.

Arquivos de vídeo M3U8

Veja um exemplo no código a seguir:

clique em e visualize o código de exemplo

<?php
/**
 * Created by Aliyun ApsaraVideo VOD.
 */
require_once dirname(__DIR__) . DIRECTORY_SEPARATOR . 'voduploadsdk' . DIRECTORY_SEPARATOR . 'Autoloader.php';
date_default_timezone_set('PRC');
// Test uploading a local M3U8 video.
function testUploadLocalM3u8($accessKeyId, $accessKeySecret, $m3u8FilePath)
{
    try {
        $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
        $uploadVideoRequest = new UploadVideoRequest($m3u8FilePath, 'testUploadLocalM3u8 via PHP-SDK');
        // Call the API to parse the list of shard addresses from the M3U8 file. If the parsing result is inaccurate, concatenate the address list yourself. By default, the shard files and the M3U8 file are in the same directory.
        $sliceFiles = $uploader->parseM3u8File($m3u8FilePath);
        //print_r($sliceFiles);
        $res = $uploader->uploadLocalM3u8($uploadVideoRequest, $sliceFiles);
        print_r($res);
    } catch (Exception $e) {
        printf("testUploadLocalM3u8 Failed, ErrorMessage: %s\n Location: %s %s\n Trace: %s\n",
            $e->getMessage(), $e->getFile(), $e->getLine(), $e->getTraceAsString());
    }
}

// Test uploading a web M3U8 video.
function testUploadWebM3u8($accessKeyId, $accessKeySecret, $m3u8FileUrl)
{
    try {
        $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
        $uploadVideoRequest = new UploadVideoRequest($m3u8FileUrl, 'testUploadWebM3u8 via PHP-SDK');
        // Call the API to parse the list of shard addresses from the M3U8 file. If the parsing result is inaccurate, concatenate the address list yourself. By default, the shard files and the M3U8 file are in the same directory.
        $sliceFileUrls = $uploader->parseM3u8File($m3u8FileUrl);
        //print_r($sliceFileUrls);
        $res = $uploader->uploadWebM3u8($uploadVideoRequest, $sliceFileUrls);
        print_r($res);
    } catch (Exception $e) {
        printf("testUploadWebM3u8 Failed, ErrorMessage: %s\n Location: %s %s\n Trace: %s\n",
            $e->getMessage(), $e->getFile(), $e->getLine(), $e->getTraceAsString());
    }
}
####  Run the test code   ####
// The AccessKey pair of an Alibaba Cloud account has permissions to access all APIs. Use the AccessKey pair of a RAM user for API access or daily O&M.
// Do not hard-code the AccessKey ID and AccessKey secret into your project code. This can lead to an AccessKey pair leak and compromise the security of all resources in your account.
// This example shows how to use an AccessKey pair from environment variables to authenticate API access. Before you run the sample code, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');
$accessKeySecret = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');
$localM3u8FilePath = '/opt/video/m3u8/sample.m3u8';
//testUploadLocalM3u8($accessKeyId, $accessKeySecret, $localM3u8FilePath);

// Example webM3u8FileURL: http://example-bucket-****.cn-shanghai.aliyuncs.com/b55b904bc612463b812990b7c8cc****/daa30814c0c340cf8199926f78aa****-195a25af366b5edae324c47e99a0****-ld.m3u8?auth_key=1608775606-0-0-9fb038deaecd009dadd86721c585****
$webM3u8FileURL = '<your webM3u8FileURL>';
//testUploadWebM3u8($accessKeyId, $accessKeySecret, $webM3u8FileURL);

Aceleração de upload

Para fazer upload de arquivos grandes (em GB ou TB) ou fazer uploads entre regiões, como enviar um vídeo da China continental para um endereço de armazenamento na região Singapore, ative o recurso de aceleração de upload. Para obter mais informações, consulte Activation method. Após ativar esse recurso, adicione o par AccelerateConfig chave-valor ao objeto UserData na configuração de upload. Se o objeto UserData não existir, crie-o. Veja um exemplo no código a seguir:

$userData = array(  
    "AccelerateConfig"=>array("Type"=>"oss","Domain"=>"****Bucket.oss-accelerate.aliyuncs.com"),
);       
$uploadVideoRequest->setUserData(json_encode($userData));

Descrição dos parâmetros

Nome

Tipo

Descrição

Type

string

Tipo de aceleração de upload a ser ativado. O parâmetro aceita somente oss.

Domain

string

Endpoint de aceleração do bucket do usuário. O endpoint usa HTTPS por padrão.

Nota

Use um endpoint de aceleração atribuído após a ativação, por exemplo, vod-***.oss-accelerate.aliyuncs.com.

Upload em lote de vários vídeos

Cada chamada a uploadLocalVideo ou uploadWebVideo faz upload de apenas um arquivo de vídeo. O SDK não aceita upload em lote de vários vídeos em uma única chamada. Para fazer upload de vários vídeos em lote, chame a operação UploadMediaByUrl.

Quando você faz upload de vídeos em lote na página de upload no console, a página também processa os vídeos um por vez. Se precisar fazer upload de arquivos grandes ou de um lote de arquivos, recomendamos usar a ferramenta de cliente para PC.

Cenário 2: fazer upload de imagens

clique em e visualize o código de exemplo

clique em e visualize o código de exemplo

<?php
/**
 * Created by Aliyun ApsaraVideo VoD.
 * User: https://www.aliyun.com/product/vod
 */

require_once dirname(__DIR__) . DIRECTORY_SEPARATOR . 'voduploadsdk' . DIRECTORY_SEPARATOR . 'Autoloader.php';

date_default_timezone_set('PRC');

// Test uploading a local image.
function testUploadLocalImage($accessKeyId, $accessKeySecret, $filePath)
{
    try {
        $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
        $uploadImageRequest = new UploadImageRequest($filePath, 'testUploadLocalImage via PHP-SDK');
        $uploadImageRequest->setCateId(1000009458);
        $res = $uploader->uploadLocalImage($uploadImageRequest);
        print_r($res);
    } catch (Exception $e) {
        printf("testUploadLocalImage Failed, ErrorMessage: %s\n", $e->getMessage());
    }

}

// Test uploading a web image.
function testUploadWebImage($accessKeyId, $accessKeySecret, $fileURL)
{
    try {
        $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
        $uploadImageRequest = new UploadImageRequest($fileURL, 'testUploadWebImage via PHP-SDK');
        $uploadImageRequest->setCateId(1000009458);
        $res = $uploader->uploadWebImage($uploadImageRequest);
        print_r($res);
    } catch (Exception $e) {
        printf("testUploadWebImage Failed, ErrorMessage: %s\n", $e->getMessage());
    }

}

####  Run the test code   ####
// The AccessKey pair of an Alibaba Cloud account has permissions to access all APIs. Use the AccessKey pair of a RAM user for API access or daily O&M.
// Do not hard-code the AccessKey ID and AccessKey secret into your project code. This can lead to an AccessKey pair leak and compromise the security of all resources in your account.
// This example shows how to use an AccessKey pair from environment variables to authenticate API access. Before you run the sample code, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');
$accessKeySecret = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');

$localFilePath = '/opt/image/test-image.jpg';
//testUploadLocalImage($accessKeyId, $accessKeySecret, $localFilePath);

$webFileURL = 'http://vod-download.cn-shanghai.aliyuncs.com/retina/pic/20180208/496AE240-54AE-4CC8-8578-3EEC8F38****.gif';
testUploadWebImage($accessKeyId, $accessKeySecret, $webFileURL);

Cenário 3: fazer upload de ativos de mídia auxiliares

Veja um exemplo no código a seguir:

clique em e visualize o código de exemplo

clique em e visualize o código de exemplo

<?php
/**
 * Created by Aliyun ApsaraVideo VoD.
 * User: https://www.aliyun.com/product/vod
 */

require_once dirname(__DIR__) . DIRECTORY_SEPARATOR . 'voduploadsdk' . DIRECTORY_SEPARATOR . 'Autoloader.php';

date_default_timezone_set('PRC');

// Test uploading a local auxiliary media asset.
function testUploadLocalAttachedMedia($accessKeyId, $accessKeySecret, $filePath)
{
    try {
        $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
        $uploadAttachedRequest = new UploadAttachedMediaRequest($filePath, 'watermark',
            'testUploadLocalAttachedMedia via PHP-SDK');
        //$uploadAttachedRequest->setCateId(100000****);
        $res = $uploader->uploadLocalAttachedMedia($uploadAttachedRequest);
        print_r($res);
    } catch (Exception $e) {
        printf("testUploadLocalAttachedMedia Failed, ErrorMessage: %s\n", $e->getMessage());
    }

}

// Test uploading a web auxiliary media asset.
function testUploadWebAttachedMedia($accessKeyId, $accessKeySecret, $fileURL)
{
    try {
        $uploader = new AliyunVodUploader($accessKeyId, $accessKeySecret);
        $uploadAttachedRequest = new UploadAttachedMediaRequest($fileURL, 'watermark',
            'testUploadWebAttachedMedia via PHP-SDK');
        //$uploadAttachedRequest->setCateId(100000****);
        $res = $uploader->uploadWebAttachedMedia($uploadAttachedRequest);
        print_r($res);
    } catch (Exception $e) {
        printf("testUploadWebAttachedMedia Failed, ErrorMessage: %s\n", $e->getMessage());
    }

}

####  Run the test code   ####
// The AccessKey pair of an Alibaba Cloud account has permissions to access all APIs. Use the AccessKey pair of a RAM user for API access or daily O&M.
// Do not hard-code the AccessKey ID and AccessKey secret into your project code. This can lead to an AccessKey pair leak and compromise the security of all resources in your account.
// This example shows how to use an AccessKey pair from environment variables to authenticate API access. Before you run the sample code, configure the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables.
$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');
$accessKeySecret = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');

$localFilePath = '/opt/image/test.png';
//testUploadLocalAttachedMedia($accessKeyId, $accessKeySecret, $localFilePath);

$webFileURL = 'http://vod-download.cn-shanghai.aliyuncs.com/retina/pic/20180208/496AE240-54AE-4CC8-8578-3EEC8F38****.gif';
testUploadWebAttachedMedia($accessKeyId, $accessKeySecret, $webFileURL);

Referências

Overview of media upload

Overview of STS SDKs