Todos os produtos
Search

Este produto

    :Initialization (Node.js SDK)

    Central de documentação

    :Initialization (Node.js SDK)

    Última atualização: Sep 24, 2026

    O Client é o ponto de entrada principal do OSS SDK for Node.js, usado para gerenciar recursos do OSS, como buckets e objetos. Para fazer solicitações ao OSS, inicialize primeiro uma instância Client e, opcionalmente, personalize a configuração padrão.

    Notas de uso

    • Configure as credenciais de acesso antes de inicializar uma instância OSSClient. Este tópico apresenta um exemplo com variáveis de ambiente. Para mais informações, consulte Configure access credentials (Node.js SDK).

    • Para mais informações sobre as regiões do OSS e seus endpoints correspondentes, consulte Regions and endpoints.

    • Para obter instruções sobre como criar um par de AccessKey de um usuário do Resource Access Management (RAM), consulte Create an AccessKey pair.

    Pré-requisitos

    Importante

    Antes de configurar o Client, defina as variáveis de ambiente com o AccessKey de um usuário do RAM.

    1. Create an AccessKey pair for a Resource Access Management (RAM) user that has full OSS access permissions.

      Criar um par de AccessKey usando o ROS

      Crie rapidamente um par de AccessKey para um usuário do RAM com permissões totais de acesso ao OSS por meio de um script do Resource Orchestration Service (ROS). Para isso, acesse o assistente de criação de pilha baseada em modelo, selecione I confirm that Alibaba Cloud ROS may create RAM resources na seção Security Confirmation e clique em Create.

      1.png

      Após criar o par de AccessKey, copie-o na guia Outputs.

      image

    2. Configure as variáveis de ambiente para o par de AccessKey.

      Linux

      1. Execute os seguintes comandos na CLI para adicionar as configurações de variáveis de ambiente ao arquivo ~/.bashrc:

        echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

        1. Aplique as alterações.

          source ~/.bashrc

        2. Verifique se as variáveis de ambiente entraram em vigor:

          echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

      macOS

      1. Execute o seguinte comando no terminal para exibir o tipo de shell padrão:

        echo $SHELL

        1. Configure as variáveis de ambiente com base no tipo de shell padrão.

          Zsh

          1. Execute os seguintes comandos para adicionar as configurações de variáveis de ambiente ao arquivo ~/.zshrc:

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

          2. Aplique as alterações.

            source ~/.zshrc

          3. Verifique se as variáveis de ambiente entraram em vigor:

            echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

          Bash

          1. Execute os seguintes comandos para adicionar as configurações de variáveis de ambiente ao arquivo ~/.bash_profile:

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

          2. Aplique as alterações.

            source ~/.bash_profile

          3. Verifique se as variáveis de ambiente entraram em vigor:

            echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

      Windows

      CMD

      1. Execute os seguintes comandos no CMD:

        setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

        1. Verifique se as variáveis de ambiente entraram em vigor:

          echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%

      PowerShell

      1. Execute os seguintes comandos no PowerShell:

        [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

        1. Verifique se as variáveis de ambiente entraram em vigor:

          [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

    3. Depois de definir as variáveis de ambiente, reinicie quaisquer sessões de terminal ou IDEs abertas para que as alterações entrem em vigor.

    Exemplos de configuração padrão

    Os exemplos de código a seguir mostram como configurar uma instância OSSClient com a Signature V4 e a Signature V1.

    Signature V4 (recomendado)

    Importante

    • Ao inicializar uma instância OSSClient com o algoritmo Signature V4, especifique o ID da região do OSS. Esse ID identifica a região de destino da solicitação. Por exemplo, para a região China (Hangzhou), defina a região como oss-cn-hangzhou. Para outros IDs de região, consulte Regions and endpoints.

    • No código, declare explicitamente o uso do algoritmo Signature V4. Por exemplo: authorizationV4: true.

    O código a seguir mostra como configurar uma instância OSSClient com um nome de domínio do OSS e a Signature V4.

    O exemplo a seguir demonstra a inicialização do Client com variáveis de ambiente para as credenciais e um endpoint público.

    const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use the Signature V4 algorithm.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to the public endpoint of the region where the bucket is located. For example, for China (Hangzhou), set endpoint to https://oss-cn-hangzhou.aliyuncs.com.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

    Signature V1 (não recomendado)

    Importante

    A partir de 1º de março de 2025, o Alibaba Cloud Object Storage Service (OSS) não oferece mais a Signature V1 para novos usuários (ou seja, novos UIDs). A partir de 1º de setembro de 2025, o OSS deixará de atualizar e manter a Signature V1, e não a disponibilizará para novos buckets de armazenamento de objetos. Migre para a Signature V4 o mais breve possível para evitar interrupções no serviço. Para mais informações, consulte Comunicado.

    O código a seguir mostra como configurar uma instância OSSClient com um nome de domínio do OSS. Para mais informações sobre os nomes de domínio do OSS para diferentes regiões, consulte Regions and endpoints.

    Criar uma instância Client usando um nome de domínio do OSS

    O código a seguir mostra como inicializar uma instância com um nome de domínio do OSS.

    const OSS = require('ali-oss');

const client = new OSS({
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'yourRegion',
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
});

    Criar uma instância Client usando um nome de domínio personalizado

    O código a seguir mostra como criar uma instância Client com um nome de domínio personalizado. Para mais informações sobre como acessar o OSS com um nome de domínio personalizado, consulte Access OSS using a custom domain name.

    Importante

    Não é possível usar o método client.listBuckets() com um nome de domínio personalizado.

    const OSS = require('ali-oss')

const client = new OSS({  
 // Use a custom domain name as the endpoint.
 endpoint: 'http://img.example.com', 
 // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
 accessKeyId: process.env.OSS_ACCESS_KEY_ID,
 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
 cname: true,
 // Set bucket to the name of your bucket.
 bucket: 'yourBucketName',
});

    Exemplos de configuração para casos de uso comuns

    Os exemplos de código a seguir mostram como configurar outros nomes de domínio. Por padrão, esses exemplos usam a Signature V4 e o AccessKey de um usuário do RAM.

    Exemplo de configuração de nome de domínio interno

    Se sua aplicação estiver implantada em uma instância ECS do Alibaba Cloud e precisar acessar recursos do OSS na mesma região com frequência, use um nome de domínio interno para reduzir os custos de tráfego e melhorar a velocidade de acesso.

    O código a seguir mostra como configurar uma instância OSSClient com um nome de domínio interno do OSS.

    const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  //Use Signature V4.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to the internal endpoint of the region where the bucket is located. For example, for China (Hangzhou), set endpoint to https://oss-cn-hangzhou-internal.aliyuncs.com.
  endpoint: 'yourEndpoint',
});

    Exemplo de configuração de nome de domínio personalizado

    O código a seguir mostra como configurar uma instância OSSClient com um nome de domínio personalizado.

    Aviso

    Primeiro, vincule o nome de domínio personalizado ao nome de domínio padrão do bucket. Caso contrário, ocorrerá um erro. Para mais informações sobre como vincular um nome de domínio personalizado, consulte Access OSS using a custom domain name.

    const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use the Signature V4 algorithm.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to your custom domain name. For example, https://static.example.com.
  endpoint: 'yourEndpoint',
  // Set cname to true to enable the CNAME option.
  cname: true,
});

    Exemplo de configuração de endpoint de aceleração

    O código a seguir mostra como configurar uma instância OSSClient com um endpoint de aceleração.

    const OSS = require('ali-oss');

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  //Use Signature V4.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to an acceleration endpoint. For example, oss-accelerate.aliyuncs.com.
  endpoint: 'oss-accelerate.aliyuncs.com',
});

    Referências

    Para mais informações sobre as opções de configuração do OSSClient, consulte Exemplos no GitHub.