Todos os produtos
Search

Este produto

    Object Storage Service:Configure callbacks de upload para aplicativos móveis

    Central de documentação

    Object Storage Service:Configure callbacks de upload para aplicativos móveis

    Última atualização: Jul 03, 2026

    Este tópico descreve como configurar um serviço de transferência direta de dados para aplicativos móveis usando o Object Storage Service (OSS) e como definir callbacks de upload.

    Informações básicas

    O tópico Configurar transferência direta de dados para aplicativos móveis explica como estabelecer um serviço de transferência direta de dados para aplicativos móveis com o OSS. No entanto, essa solução apresenta uma limitação. Em aplicativos móveis Android e iOS, é possível solicitar um token do Security Token Service (STS) uma única vez e utilizá-lo para enviar dados ao OSS várias vezes. Consequentemente, o servidor de aplicação não consegue identificar quais dados o usuário enviou, o que dificulta o gerenciamento das informações pelo desenvolvedor. Para resolver esse problema, o OSS oferece o recurso de callback de upload.

    Procedimento

    O fluxo de desenvolvimento de um callback de upload segue as etapas abaixo:

    image

    Após receber dados de um aplicativo Android ou iOS (Etapa 5 na figura) e antes de retornar o resultado do upload ao usuário (Etapa 7), o OSS aciona uma tarefa de callback de upload (Etapa 6). Durante o callback, o OSS envia uma solicitação ao seu servidor de aplicação, aguarda uma resposta e, em seguida, encaminha essa resposta para o aplicativo Android ou iOS. Para obter mais informações, consulte Callback.

    Finalidade dos callbacks de upload

    • Os callbacks de upload notificam o servidor de aplicação sobre as informações básicas de um arquivo enviado.

      Essas informações podem incluir uma ou mais variáveis da tabela a seguir. O aplicativo Android ou iOS especifica o formato do conteúdo retornado durante o upload.

      Variável de sistema

      Descrição

      bucket

      Bucket para o qual o aplicativo móvel envia o arquivo.

      object

      Nome do arquivo após o envio para o OSS pelo aplicativo móvel.

      etag

      ETag do arquivo enviado. Corresponde ao campo etag retornado ao usuário.

      size

      Tamanho do arquivo enviado.

      mimeType

      Tipo de recurso.

      imageInfo.height

      Altura da imagem.

      imageInfo.width

      Largura da imagem.

      imageInfo.format

      Formato da imagem, como JPG ou PNG.

    • Os callbacks de upload também permitem definir parâmetros personalizados para transmitir informações adicionais.

      Como desenvolvedor, você pode precisar conhecer a versão do aplicativo do usuário, a versão do sistema operacional, informações de GPS e o modelo do telefone. Para isso, especifique os seguintes parâmetros personalizados quando um dispositivo Android ou iOS enviar um arquivo:

      • x:version: Define a versão do aplicativo.

      • x:system: Define a versão do sistema operacional.

      • x:gps: Define as informações de GPS.

      • x:phone: Define o modelo do telefone.

      O aplicativo Android ou iOS inclui esses parâmetros ao enviar um arquivo para o OSS. Em seguida, o OSS adiciona tais parâmetros ao CallbackBody e os envia ao servidor de aplicação, permitindo que o servidor receba as informações.

    Requisitos para o servidor de aplicação

    • Implante um serviço capaz de receber solicitações POST. Esse serviço deve possuir um endereço de rede pública, como http://example.com/callback.php.

    • O serviço deve retornar uma resposta válida ao OSS. A resposta precisa estar no formato JSON e pode conter conteúdo personalizado. O OSS encaminha essa resposta do servidor de aplicação para o aplicativo Android ou iOS. Para obter mais informações, consulte Callback.

    Configurar um callback de upload no aplicativo móvel

    Para acionar um callback de upload quando o OSS receber uma solicitação de envio, inclua o seguinte conteúdo ao construir a solicitação de upload no aplicativo móvel:

    • A url de callback (callbackUrl). Trata-se da url do servidor para o qual a solicitação de callback será enviada, como http://example.com/callback.php. Esse endereço deve ser acessível pela Internet.

    • O corpo da solicitação de callback (callbackBody) enviado ao servidor de aplicação. O corpo pode incluir uma ou mais variáveis de sistema fornecidas pelo OSS.

    Suponha que a url de callback de upload do seu servidor de aplicação seja http://example.com/callback.php. Você deseja obter o nome e o tamanho do arquivo enviado, além de ter definido a variável x:phone para o modelo do telefone e a variável x:system para a versão do sistema operacional.

    A seguir, são apresentados dois exemplos de callbacks de upload:

    • Exemplo de configuração de callback de upload no iOS:

      OSSPutObjectRequest * request = [OSSPutObjectRequest new];
request.bucketName = @"<bucketName>";
request.objectKey = @"<objectKey>";
request.uploadingFileURL = [NSURL fileURLWithPath:@"<filepath>"];
// Set callback parameters.
request.callbackParam = @{
                          @"callbackUrl": @"http://example.com/callback.php",
                          @"callbackBody": @"filename=${object}&size=${size}&phone=${x:phone}&system=${x:system}"
                          };
// Set custom variables.
request.callbackVar = @{
                        @"x:phone": @"iphone6s",
                        @"x:system": @"ios9.1"
                        };

    • Exemplo de configuração de callback de upload no Android:

      PutObjectRequest put = new PutObjectRequest(testBucket, testObject, uploadFilePath);
ObjectMetadata metadata = new ObjectMetadata();
metadata.setContentType("application/octet-stream");
put.setMetadata(metadata);
put.setCallbackParam(new HashMap<String, String>() {
    {
        put("callbackUrl", "http://example.com/callback.php");
        put("callbackBody", "filename=${object}&size=${size}&phone=${x:phone}&system=${x:system}");
    }
});
put.setCallbackVars(new HashMap<String, String>() {
     {
         put("x:phone", "iPhone 6s");
         put("x:system", "YunOS5.0");
     }
});

    Solicitação de callback recebida pelo servidor de aplicação

    A solicitação de callback recebida pelo servidor de aplicação varia conforme a url e o corpo de callback configurados. O código a seguir fornece um exemplo:

    POST /index.html HTTP/1.0
Host: 203.0.113.0
Connection: close
Content-Length: 81
Content-Type: application/x-www-form-urlencoded
User-Agent: ehttp-client/0.0.1
authorization: kKQe**************/kdD1ktNVgbWE**************
x-oss-pub-key-url: aHR0**************
filename=test.txt&size=5&phone=iphone6s&system=ios9.1

    Para obter mais informações, consulte a referência da api Callback.

    Verificar se a solicitação de callback é originária do OSS

    Caso seu servidor de callback seja alvo de ataques maliciosos, como o recebimento de solicitações de callback falsificadas que interrompem as operações normais, verifique se cada solicitação de callback provém do OSS.

    Para isso, valide os parâmetros x-oss-pub-key-url e authorization no cabeçalho que o OSS envia ao servidor de aplicação usando RSA. Uma solicitação só é considerada originária do OSS se passar pela validação RSA. Os programas de exemplo neste tópico demonstram essa implementação para sua referência.

    Processar a solicitação de callback

    O servidor de aplicação verifica se a solicitação é originária do OSS e define o formato do conteúdo para o callback, como

    filename=test.txt&size=5&phone=iphone6s&system=ios9.1

    O servidor de aplicação pode analisar o conteúdo retornado pelo OSS para obter os dados necessários. Após obter os dados, armazene-os para gerenciamento futuro.

    Como o OSS processa a resposta do servidor de aplicação

    Dois cenários podem ocorrer:

    • O OSS envia a solicitação de callback ao servidor de aplicação, mas o servidor falha ao recebê-la ou está inacessível. Nesse caso, o OSS retorna o código de status 203 para o aplicativo Android ou iOS. Os dados já estão armazenados no OSS.

    • O servidor de aplicação recebe a solicitação de callback do OSS e retorna uma resposta válida. Nessa situação, o OSS retorna o código de status 200 para o aplicativo Android ou iOS e encaminha a resposta do servidor de aplicação para o aplicativo.

    Baixe programas de exemplo

    Os programas de exemplo demonstram apenas como verificar a assinatura recebida pelo servidor de aplicação. Adicione seu próprio código para analisar o conteúdo do corpo do callback.

    • Java

      • url de download.

      • Como executar: Após descompactar o pacote, execute java -jar oss-callback-server-demo.jar 9000. Neste exemplo, 9000 é o número da porta, que você pode alterar.

        Nota

        Este exemplo JAR foi testado no Java 1.7. Se encontrar problemas, talvez seja necessário modificar o código. Este é um projeto Maven.

    • PHP

      • url de download.

      • Como executar: Implante o pacote descompactado em um ambiente Apache. Devido à natureza do PHP, o método para recuperar alguns cabeçalhos depende do ambiente. Consulte o exemplo e modifique-o conforme necessário para o seu ambiente específico.

    • Python

      • url de download.

      • Como executar: Após descompactar o pacote, execute python callback_app_server.py. O programa implementa um servidor HTTP simples. Talvez seja necessário instalar a dependência RSA para executar este programa.

    • Versão Ruby

    Perguntas frequentes

    Posso alterar a url de callback para que outro servidor receba o callback e confirme o status do upload?

    Não. O lado do servidor do OSS assina e verifica os parâmetros. Qualquer conteúdo adulterado falhará na validação.