Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Upload files using the PHP SDK

Última atualização: Jun 27, 2026

Este tópico apresenta exemplos detalhados de uso do kit de desenvolvimento de software (SDK) de upload server-side para PHP no envio de diversos arquivos de mídia ao 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 Processo de upload. O fluxo básico de utilização do SDK de upload para PHP é:

  1. Cumpra os pré-requisitos. Para mais informações, veja Pré-requisitos.

  2. Integre o SDK de upload para PHP. Consulte Integrar o SDK de upload para PHP.

  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 (Xangai). Para enviar arquivos de mídia a 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 abaixo demonstra como definir a região de upload para cn-beijing (Pequim):

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

Pré-requisitos

  • Ative o ApsaraVideo VOD. Para mais detalhes, consulte Ativar o 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 Gerenciar buckets de armazenamento e Configurar callbacks.

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

  • Configure as variáveis de ambiente ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET. Para mais detalhes, consulte Configurar variáveis de ambiente no Linux, macOS e Windows.

    Importante
    • O par de AccessKey de uma conta Alibaba Cloud possui permissões em todas as operações de API. Utilize o par de 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) Caso deseje acessar o ApsaraVideo VOD por meio do Security Token Service (STS), crie uma função para o usuário RAM e conceda a ela as permissões necessárias. Para mais informações, consulte Obter um token STS.

Integrar o 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 upload de vídeos. Para detalhes sobre os campos, consulte CreateUploadVideo.

  • UploadImageRequest.php

    Diretório

    Descrição

    UploadImageRequest

    Classe de solicitação para upload de imagens. Para detalhes 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 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 IDs de região do ApsaraVideo VOD.

    uploadLocalVideo

    Interface para upload de vídeos locais.

    uploadWebVideo

    Interface para upload de vídeos da web.

    uploadLocalImage

    Faz o upload de imagens locais.

    uploadWebImage

    Faz o upload de imagens da web.

    uploadLocalAttachedMedia

    Faz o upload de ativos de mídia auxiliares locais.

    uploadWebAttachedMedia

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

    uploadLocalM3u8

    Faz o upload de arquivos M3U8 locais.

    uploadWebM3u8

    Faz o upload de arquivos M3U8 da web.

    parseM3u8File

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

    setEcsRegionId

    Defina a região onde o script de upload está implantado em uma instância ECS, se aplicável. Se a região for igual à região de 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, encontra-se 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.

  • 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 do 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 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: Upload de arquivos de áudio e vídeo

Arquivos padrão de áudio e vídeo

É possível fazer o upload dos seguintes tipos de arquivos de áudio e vídeo:

  • Faça o upload de arquivos locais via multipart upload. Um único arquivo pode ter até 48,8 TB. Não há suporte para upload retomável. Consulte a função testUploadLocalVideo.

  • Faça o upload de arquivos da web especificando uma URL. O tamanho máximo por arquivo é de 48,8 TB. Este método exige o download do arquivo da web para um disco local antes do envio. Certifique-se de haver espaço suficiente em disco. Consulte a função testUploadWebVideo.

Clique em 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('6ae347b0140181ad371d197ebe289****');
        $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);

Arquivos de vídeo M3U8

Exemplo de código:

Clique em 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 Singapura, ative o recurso de aceleração de upload. Para mais informações, consulte Método de ativação. Após ativar esse recurso, adicione o par chave-valor AccelerateConfig ao objeto UserData na configuração de upload. Caso o objeto UserData não exista, crie-o. Exemplo de código:

$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. Apenas oss é compatível.

Domain

string

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: Upload de imagens

Clique em para visualizar o código de exemplo

Clique em 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: Upload de ativos de mídia auxiliares

Exemplo de código:

Clique em para visualizar o código de exemplo

Clique em 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);

Códigos de erro

Referências

Visão geral do upload de mídia

Visão geral dos SDKs STS