How to initialize an OSSClient instance - Object Storage Service: Central de Documentação do Alibaba Cloud

O OSSClient é o cliente iOS do Object Storage Service (OSS). Ele fornece métodos para gerenciar recursos como buckets e objetos. Antes de usar o SDK para enviar solicitações ao OSS, inicialize e configure uma instância do OSSClient.

Nota

O ciclo de vida de uma instância do OSSClient deve corresponder ao ciclo de vida do aplicativo. Crie uma instância global do OSSClient ao iniciar o aplicativo e destrua-a ao encerrá-lo.

Inicializar um OSSClient

Importante

Um dispositivo móvel é um ambiente não confiável. Armazenar o AccessKeyId e o AccessKeySecret diretamente no dispositivo para assinar solicitações gera um alto risco de segurança. Para maior segurança, use a autenticação do Security Token Service (STS) ou o modo autoassinado.

Crie uma instância do OSSClient de uma das seguintes formas:

Criar um OSSClient usando o STS

O código a seguir demonstra como criar um OSSClient com o STS.

// Set yourEndpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
NSString *endpoint = @"yourEndpoint";
// The temporary AccessKey pair obtained from STS, which consists of an AccessKey ID and an AccessKey secret.
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// The security token obtained from STS.
NSString *securityToken = @"yourSecurityToken";
NSString *region = @"yourRegion";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
configuration.signVersion = OSSSignVersionV4;
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];
client.region = region;

Criar um OSSClient usando um nome de domínio personalizado

O código a seguir exemplifica a criação de um OSSClient com um nome de domínio personalizado.

// Set yourEndpoint to a custom domain name.
NSString *endpoint = @"yourEndpoint";
// The temporary AccessKey pair obtained from STS, which consists of an AccessKey ID and an AccessKey secret.
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// The security token obtained from STS.
NSString *securityToken = @"yourSecurityToken";
NSString *region = @"yourRegion";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
configuration.signVersion = OSSSignVersionV4;
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];
client.region = region;

Criar um OSSClient em um ambiente Apsara Stack ou de domínio privado

O exemplo a seguir ilustra a criação de um OSSClient em um ambiente Apsara Stack ou de domínio privado.

// Set yourEndpoint to the endpoint of the region where the bucket is located.
NSString *endpoint = @"yourEndpoint";
// The temporary AccessKey pair obtained from STS, which consists of an AccessKey ID and an AccessKey secret.
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// The security token obtained from STS.
NSString *securityToken = @"yourSecurityToken";
NSString *region = @"yourRegion";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
// Skip CNAME resolution.
configuration.cnameExcludeList = @[endpoint];
configuration.signVersion = OSSSignVersionV4;
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];
client.region = region;

Configurar um OSSClient

O ClientConfiguration é a classe de configuração do OSSClient. Use esta classe para configurar parâmetros como proxy, tempo limite de conexão e número máximo de conexões.

Parâmetro	Descrição	Método
maxRetryCount	Número máximo de tentativas para uma solicitação com falha. O valor padrão é 3.	configuration.maxRetryCount
maxConcurrentRequestCount	Número máximo de solicitações simultâneas. O valor padrão é 5.	configuration.maxConcurrentRequestCount
enableBackgroundTransmitService	Define se as tarefas em segundo plano serão ativadas. Por padrão, esse recurso fica desativado.	configuration.enableBackgroundTransmitService
backgroundSesseionIdentifier	Identificador personalizado da sessão em segundo plano. O valor padrão é `com.aliyun.oss.backgroundsession`.	configuration.backgroundSesseionIdentifier
isHttpdnsEnable	Define se o HttpDNS será ativado. true: o HttpDNS é ativado por padrão nas versões 2.10.14 e anteriores. false: o HttpDNS é desativado por padrão nas versões 2.10.14 e posteriores.	configuration.isHttpdnsEnable
timeoutIntervalForRequest	Intervalo de tempo limite da solicitação. O valor padrão é 15 segundos.	configuration.timeoutIntervalForRequest
timeoutIntervalForResource	Intervalo de tempo limite do recurso. O valor padrão é 7 dias.	configuration.timeoutIntervalForResource
proxyHost	Endereço do host do servidor proxy.	configuration.proxyHost
proxyPort	Porta do servidor proxy.	configuration.proxyPort
userAgentMark	Cabeçalho User-Agent nas solicitações HTTP.	configuration.userAgentMark
cnameExcludeList	Os elementos desta lista ignoram a resolução de nome canônico (CNAME).	configuration.cnameExcludeList
crc64Verifiable	Define se a verificação de código de redundância cíclica de 64 bits (CRC64) será ativada. Valores válidos: YES: ativa a verificação CRC64. NO (padrão): desativa a verificação CRC64.	configuration.crc64Verifiable
isAllowUACarrySystemInfo	Define se o User-Agent pode transportar informações do sistema. Valores válidos: YES: permite que o User-Agent transporte informações do sistema. NO (padrão): impede que o User-Agent transporte informações do sistema.	configuration.isAllowUACarrySystemInfo
isFollowRedirectsEnable	Define se o redirecionamento HTTP será ativado. Valores válidos: YES: ativa o redirecionamento HTTP. NO (padrão): desativa o redirecionamento HTTP.	configuration.isFollowRedirectsEnable

O código abaixo ilustra o uso do ClientConfiguration para definir os parâmetros do OSSClient.

// Set yourEndpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
NSString *endpoint = @"yourEndpoint";
// The temporary AccessKey pair obtained from STS, which consists of an AccessKey ID and an AccessKey secret.
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// The security token obtained from STS.
NSString *securityToken = @"yourSecurityToken";
NSString *region = @"yourRegion";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
// Use Signature V4.
configuration.signVersion = OSSSignVersionV4;
// The maximum number of retries for a failed request.
configuration.maxRetryCount = 3;
// The maximum number of concurrent requests.
configuration.maxConcurrentRequestCount = 3;
// Specifies whether to enable background tasks.
configuration.enableBackgroundTransmitService = YES;
// The custom identifier for the background session.
configuration.backgroundSesseionIdentifier = @"yourBackgroundSesseionIdentifier";
// Specifies whether to enable HttpDNS.
configuration.isHttpdnsEnable = YES;
// The request timeout interval.
configuration.timeoutIntervalForRequest = 15;
// The resource timeout interval.
configuration.timeoutIntervalForResource = 24 * 60 * 60;
// The host address of the proxy server.
configuration.proxyHost = @"yourProxyHost";
// The port of the proxy server.
configuration.proxyPort = @8080;
// The User-Agent header in HTTP requests.
configuration.userAgentMark = @"yourUserAgent";
// The elements in this list will skip CNAME resolution.
configuration.cnameExcludeList = @[@"yourCname"];
// Specifies whether to enable CRC64 verification.
configuration.crc64Verifiable = YES;
// Specifies whether to allow the User-Agent to carry system information.
configuration.isAllowUACarrySystemInfo = YES;
// Specifies whether to enable HTTP redirection.
configuration.isFollowRedirectsEnable = NO;

OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];
client.region = region;

Ativar logs

Dispositivos móveis operam em ambientes complexos, e o SDK do OSS pode ficar indisponível em determinadas regiões ou horários. Para ajudar os desenvolvedores a diagnosticar problemas, o SDK do OSS pode registrar logs localmente quando a geração de logs está ativada. Antes de usar o OSSClient, inicialize-o e chame o método a seguir para ativar os logs.

// Log format.
//2017/10/25 11:05:43:863  [Debug]: 17th time: <NSThread: 0x7f8099108580>{number = 3, name = (null)}
//2017/10/25 11:05:43:863  [Debug]: 15th time: <NSThread: 0x7f80976052c0>
//2017/10/25 11:05:43:863  [Debug]: ----------TestDebug------------
// Enable logging.
[OSSLog enableLog];

Nota

Os arquivos de log são armazenados na pasta Caches/OSSLogs da sandbox.
Faça o upload dos arquivos para o seu servidor ou use o Alibaba Cloud Simple Log Service para enviá-los.

OSSTask

Todas as chamadas de API retornam um OSSTask.
```
OSSTask * task = [client getObject:get];
```
Configure o OSSTask:
- Para implementar um callback assíncrono, defina uma continuação para o OSSTask.
```
[task continueWithBlock: ^(OSSTask *task) {
    // do something
    ...
    return nil;
}];
```
- Para implementar um callback síncrono, aguarde a conclusão do OSSTask.
```
[task waitUntilFinished];
```