Object Storage Service:Instalar o OSS Browser.js SDK

Pré-requisitos

• Use um usuário RAM ou STS para acesso

  O par de AccessKey da sua conta Alibaba Cloud concede acesso total a todas as APIs. Como prática recomendada de segurança, recomendamos fortemente que não use seu par de AccessKey diretamente. Para aplicações server-side, utilize um usuário RAM ou STS para acessar a API e realizar operações rotineiras. Para aplicações client-side, use obrigatoriamente o STS para acessar a API. Para mais informações, consulte controle de acesso.

• Configure o compartilhamento de recursos de origem cruzada (CORS)

  Ao acessar o OSS diretamente pelo navegador, configure as regras de CORS no bucket conforme descrito abaixo:

  • Origin: Especifique um nome de domínio exato, como https://www.aliyun.com, ou um nome de domínio com o caractere curinga asterisco (*), como https://*.aliyun.com.

  • Allowed Methods: Selecione os métodos adequados ao seu caso de uso. Por exemplo, selecione PUT para uploads multipart e DELETE para excluir objetos.

  • Allowed Headers: Defina este campo como *.

  • Exposed Headers: Configure os cabeçalhos conforme a necessidade da aplicação. Talvez seja necessário expor ETag, x-oss-request-id e x-oss-version-id.

  

  Para mais informações, consulte Configurar CORS.

Limitações

O OSS SDK para Browser.js usa Browserify e Babel para gerar código compatível com navegadores. Devido às limitações do ambiente de navegador, os seguintes recursos não têm suporte:

• Upload via streaming: não é possível configurar codificação chunked no navegador. Use upload multipart como alternativa.

• Operações com arquivos locais: o navegador não permite acesso direto ao sistema de arquivos local. Use URLs assinadas para baixar objetos.

• O OSS não oferece suporte a solicitações cross-origin relacionadas a buckets. Execute operações de gerenciamento de buckets no console.

Baixe o SDK

Os exemplos na documentação oficial baseiam-se no SDK v6.x. Para versões anteriores à 6.x, consulte a documentação de desenvolvimento 5.x. Para atualizar para a versão 6.x, veja o guia de atualização.

• Repositório no GitHub

• Operações de API

• ChangeLog

Instale o SDK

• Navegadores com suporte

  • Internet Explorer 10 e posteriores

  • Edge

  • Versões principais do Chrome, Firefox e Safari

  • Navegadores padrão nas versões principais do Android, iOS e Windows Phone

• Métodos de instalação

  Instale o OSS SDK para Browser.js de uma das seguintes formas.

  Importar no navegador

  Importante

  Alguns navegadores, como Internet Explorer 10 e 11, não oferecem suporte nativo a Promises. Inclua uma biblioteca polyfill de Promise, como promise-polyfill.

  <!-- Import from a CDN -->
  <script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.20.0.min.js"></script>      
  <!-- Import from a local file -->
  <script src="./aliyun-oss-sdk-6.20.0.min.js"></script>

  Nota

  • A importação via CDN depende da estabilidade do servidor CDN. Recomendamos importar o SDK de um arquivo local ou compilá-lo manualmente.

  • Ao importar de um arquivo local, defina o atributo src com o caminho relativo do arquivo.

  • Este tópico usa a versão 6.20.0 como exemplo. Para outras versões, consulte ali-oss.

  Use o objeto OSS no código:

  Importante

  O OSS SDK para Browser.js geralmente executa em um ambiente de navegador. Para evitar a exposição do par de AccessKey da sua conta Alibaba Cloud (AccessKey ID e AccessKey secret), recomendamos fortemente o uso de credenciais de acesso temporárias para operações no OSS.

  As credenciais de acesso temporárias incluem um par de AccessKey temporário (AccessKey ID e AccessKey secret) e um token de segurança. Obtenha essas credenciais chamando a operação AssumeRole do STS ou usando os SDKs do STS para várias linguagens de programação. Para saber como configurar um serviço STS, consulte Usar credenciais de acesso temporárias fornecidas pelo STS para acessar o OSS.

  <script type="text/Browser.jsscript">
    const client = new OSS({
      // Set region to the region where the bucket is located. For example, if your bucket is in the China (Hangzhou) region, set region to oss-cn-hangzhou.
      region: 'yourRegion',
      // Enable V4 signature.
      authorizationV4: true,
      // The temporary AccessKey pair (AccessKey ID and AccessKey secret) obtained from STS.
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // The security token obtained from STS.
      stsToken: 'yourSecurityToken',
      refreshSTSToken: async () => {
      // Obtain temporary access credentials from your STS service.
        const info = await fetch('your_sts_server');
        return {
          accessKeyId: info.accessKeyId,
          accessKeySecret: info.accessKeySecret,
          stsToken: info.stsToken
        }
      },
      // The interval for refreshing temporary access credentials, in milliseconds.
      refreshSTSTokenInterval: 300000,
      // The bucket name.
      bucket: 'examplebucket'
    });
  </script>                           

  Instale com npm

  npm install ali-oss

  Após a instalação, importe o pacote usando import ou require. Como os navegadores não oferecem suporte nativo ao formato de módulo require, use um bundler, como webpack ou browserify, no ambiente de desenvolvimento.

  const OSS = require('ali-oss');
  
  const client = new OSS({
      // Set region to the region where the bucket is located. For example, if your bucket is in the China (Hangzhou) region, set region to oss-cn-hangzhou.
      region: 'yourRegion',
      // Enable V4 signature.
      authorizationV4: true,
      // The temporary AccessKey pair (AccessKey ID and AccessKey secret) obtained from STS.
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // The security token obtained from STS.
      stsToken: 'yourSecurityToken',
      refreshSTSToken: async () => {
      // Obtain temporary access credentials from your STS service.
        const info = await fetch('your_sts_server');
        return {
          accessKeyId: info.accessKeyId,
          accessKeySecret: info.accessKeySecret,
          stsToken: info.stsToken
        }
      },
      // The interval for refreshing temporary access credentials, in milliseconds.
      refreshSTSTokenInterval: 300000,
      // The bucket name.
      bucket: 'examplebucket'
  });

Modos de uso

O OSS SDK para Browser.js oferece suporte a modelos de programação síncrona e assíncrona. Em ambos os casos, crie uma instância de cliente com new OSS().

// Create a client instance.
const client = new OSS(...);

async function put () {
  try {
    // The name of the object to upload to OSS.
    // The file to upload from the browser. It can be an HTML5 File or Blob object.
    const r1 = await client.put('object', file);
    console.log('put success: %j', r1);
    const r2 = await client.get('object');
    console.log('get success: %j', r2);
  } catch (e) {
    console.error('error: %j', e);
  }
}

put();                    

// Create a client instance.
const client = new OSS(...);

// The name of the object to upload to OSS.
// The file to upload from the browser. It can be an HTML5 File or Blob object.
client.put('object', file).then(function (r1) {
  console.log('put success: %j', r1);
  return client.get('object');
}).then(function (r2) {
  console.log('get success: %j', r2);
}).catch(function (err) {
  console.error('error: %j', err);
});