Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Upload files using the PHP SDK

Última atualização: Aug 03, 2026

Este tópico apresenta exemplos detalhados de uso do kit de desenvolvimento de software (SDK) de envio server-side para PHP no upload de diversos arquivos de mídia para o armazenamento do ApsaraVideo VOD.

Visão geral

Nota

Recomenda-se a arquitetura B/S (Browser/Server) para desenvolvimento em PHP.

O SDK de upload para PHP segue o fluxo geral do SDK server-side do ApsaraVideo VOD. Para mais detalhes, consulte Upload process. O processo básico de uso do SDK de upload para PHP é:

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

  2. Integre o SDK de upload para PHP. Consulte Integrate the PHP upload SDK para obter instruções.

  3. Implemente a lógica de upload, incluindo a configuração das informações de envio.

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

    O exemplo abaixo demonstra como definir 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

  • Ative o ApsaraVideo VOD. Para mais informações, consulte Activate ApsaraVideo VOD.

  • Configure as definições de sistema necessárias para o upload, incluindo o caminho de armazenamento na região especificada e as configurações de callback. Consulte Manage storage buckets e Configure callbacks para mais detalhes.

  • Crie um usuário RAM para acessar o ApsaraVideo VOD. Para evitar riscos de segurança decorrentes do vazamento do par AccessKey da sua conta Alibaba Cloud, recomendamos criar um usuário RAM e conceder-lhe as permissões necessárias para acessar o ApsaraVideo VOD. Em seguida, utilize o par AccessKey desse usuário RAM para acessar o service. Para mais informações, consulte Create a RAM user and grant permissions.

  • Configure as variáveis de ambiente ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET. Para mais detalhes, consulte Configure environment variables in Linux, macOS, and Windows.

    Importante
    • O par AccessKey de uma conta Alibaba Cloud possui permissões em todas as operações de API. Utilize o par AccessKey de um usuário RAM para chamar operações de API ou executar tarefas rotineiras de O&M.

    • Não codifique rigidamente (hard-code) seu AccessKey ID e AccessKey secret no código do projeto. Em caso de vazamento, todos os recursos da sua conta ficarão comprometidos.

  • (Opcional) Crie uma função para o usuário RAM e conceda as permissões necessárias para acessar o ApsaraVideo VOD se você pretender acessar o service por meio do Security Token Service (STS). Para mais informações, consulte Obtain an STS token.

Integração do SDK de upload para PHP

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

  2. Descompacte o arquivo 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 envio de vídeos. Para detalhes sobre os campos, consulte CreateUploadVideo.

  • UploadImageRequest.php

    Diretório

    Descrição

    UploadImageRequest

    Classe de solicitação para envio de imagens. Para detalhes sobre os campos, consulte CreateUploadImage.

  • UploadAttachedMediaRequest.php

    Diretório

    Descrição

    UploadAttachedMediaRequest

    Classe de solicitação para envio de ativos de mídia auxiliares. Para detalhes sobre os campos, consulte CreateUploadAttachedMedia.

  • AliyunVodUploader.php

    Diretório

    Descrição

    __construct

    Define o AccessKey para uploads, o centro do ApsaraVideo VOD e o endpoint. Para mais informações, consulte AccessKey e ApsaraVideo VOD region IDs.

    uploadLocalVideo

    Interface para envio de vídeos locais.

    uploadWebVideo

    Interface para envio de vídeos via web.

    uploadLocalImage

    Envia imagens locais.

    uploadWebImage

    Envia imagens via web.

    uploadLocalAttachedMedia

    Envia ativos de mídia auxiliares locais.

    uploadWebAttachedMedia

    Envia ativos de mídia auxiliares via web.

    uploadLocalM3u8

    Envia arquivos M3U8 locais.

    uploadWebM3u8

    Envia arquivos M3U8 via web.

    parseM3u8File

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

    setEcsRegionId

    Define a região onde o script de upload está implantado em uma instância ECS, se aplicável. Se a região for a mesma do armazenamento do ApsaraVideo VOD, o upload via rede interna será ativado automaticamente.

    setEnableSSL

    Especifica se o SSL deve ser ativado (uso de HTTPS para requisições de rede). Por padrão, permanece desativado para evitar problemas quando extensões relacionadas não estão instaladas ou configuradas incorretamente.

    uploadProgressCallback

    Função de callback para o progresso do upload. Você pode reescrever esta função. Para a assinatura do método e um exemplo de substituição, veja abaixo.

    Assinatura do método uploadProgressCallback

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

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

    • $totalBytes: O tamanho total do arquivo em bytes.

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

    Para exibir um progresso de upload personalizado, estenda a classe AliyunVodUploader e sobrescreva este método. O exemplo a seguir demonstra como fazer isso:

    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 truncamento de strings, obtenção de extensões de arquivo e nomes de arquivo.

    AliyunVodLog

    Classe de log para impressão simples. logSwitch é o interruptor de log.

    AliyunVodDownloader

    Baixa arquivos da web.

    AliyunVodReportUpload

    Reporta o progresso do upload.

    AliyunVodError

    Define 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. Encapsula a assinatura de API da Alibaba Cloud, requisições HTTP e outras funcionalidades essenciais.

  • aliyun-php-sdk-vod: SDK de API server-side para o ApsaraVideo VOD. Encapsula as requisições para as APIs do ApsaraVideo VOD.

  • aliyun-php-sdk-oss: Dependência que fornece a classe OSS para o SDK de upload. 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 envio de vídeos.

  • uploadImage.php: Código de exemplo para envio de imagens.

  • uploadAttachedMedia.php: Código de exemplo para envio de ativos de mídia auxiliares.

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

Arquivos padrão de áudio e vídeo

É possível enviar os seguintes tipos de arquivos de áudio e vídeo:

  • Envie arquivos locais utilizando upload multipartido. Um único arquivo pode ter até 48,8 TB. Não há suporte para upload retomável. Para mais informações, consulte a função testUploadLocalVideo.

  • Envie arquivos da web especificando uma URL de arquivo. Um único arquivo pode ter até 48,8 TB. Este método exige o download do arquivo da web para um disco local antes do envio. Certifique-se de que há espaço suficiente em seu disco local. Para mais informações, consulte a função testUploadWebVideo.

Clique para visualizar 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');
        //$uploadVideoRequest->setCateId(1);
        // 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);

O método uploadLocalVideo permite especificar um grupo de modelos de transcodificação durante o envio do vídeo chamando setTemplateGroupId(). Ao especificar o ID do grupo de modelos de transcodificação, o vídeo é transcoded automaticamente assim que o upload é concluído, eliminando a necessidade de chamar separadamente a operação SubmitTranscodeJobs. 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 VOD.

Arquivos de vídeo M3U8

O código a seguir fornece um exemplo:

Clique para visualizar 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 enviar arquivos grandes (na casa de GBs ou TBs) ou realizar uploads entre regiões, como enviar um vídeo da China continental para um endereço de armazenamento na região de Singapore, ative o recurso de aceleração de upload. Para 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. Caso o objeto UserData não exista, crie-o. O código a seguir apresenta um exemplo:

$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

O tipo de aceleração de upload a ser ativado. Apenas oss é compatível.

Domain

string

O endpoint de aceleração para o bucket do usuário. HTTPS é utilizado por padrão.

Nota

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

Cenário 2: Envio de imagens

Clique para visualizar o código de exemplo

Clique para visualizar 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: Envio de ativos de mídia auxiliares

O código a seguir fornece um exemplo:

Clique para visualizar o código de exemplo

Clique para visualizar 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