Concetti

Per effettuare chiamate sincrone, creare un'istanza del client sincrono. Il pattern generale per i client sincroni è che per un servizio denominato Example, ci sarà un'interfaccia denominata ExampleService e l'implementazione del client sincrono sarà denominata ExampleServiceClient. Di seguito è riportato un esempio di creazione di un client di storage degli oggetti.

AuthenticationDetailsProvider provider = ...;
ObjectStorage clientWithDefaultClientConfig = new ObjectStorageClient(provider);
clientWithDefaultClientConfig.setRegion(Region.US_ASHBURN_1);

ClientConfiguration clientConfig = ...;
ObjectStorage clientWithExplicitClientConfig = new ObjectStorageClient(provider, clientConfig);
clientWithExplicitClientConfig.setRegion(Region.US_ASHBURN_1);

Le chiamate sincrone verranno bloccate fino a quando la risposta non sarà disponibile. Tutte le API SDK restituiscono un oggetto di risposta (indipendentemente dal fatto che l'API invii o meno contenuto). In genere, l'oggetto risposta contiene almeno un ID richiesta che è possibile utilizzare quando si contatta il Supporto Oracle per assistenza su una richiesta specifica.

ObjectStorage client = ...;
GetBucketResponse response = client.getBucket(
    GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build());
String requestId = response.getOpcRequestId();
Bucket bucket = response.getBucket();
System.out.println(requestId);
System.out.println(bucket.getName());

Per effettuare chiamate asincrone, creare un'istanza del client asincrono. Il modello generale per i client asincroni è che per un servizio denominato Esempio, ci sarà un'interfaccia denominata ExampleServiceAsync e l'implementazione client asincrona sarà denominata ExampleServiceAsyncClient. Di seguito è riportato un esempio di creazione di un client di storage degli oggetti.

AuthenticationDetailsProvider provider = ...;
ObjectStorageAsync clientWithDefaultClientConfig = new ObjectStorageAsyncClient(provider);
clientWithDefaultClientConfig.setRegion(Region.US_ASHBURN_1);
 
ClientConfiguration clientConfig = ...;
ObjectStorageAsync clientWithExplicitClientConfig = new ObjectStorageAsyncClient(provider, clientConfig);
clientWithExplicitClientConfig.setRegion(Region.US_ASHBURN_1);

Le chiamate asincrone vengono restituite immediatamente. È necessario fornire un AsyncHandler che verrà richiamato al termine della chiamata in modo corretto o non riuscito:

ObjectStorageAsync client = ...;
 
AsyncHandler<GetBucketRequest, GetBucketResponse> handler = new AsyncHandler<GetBucketRequest, GetBucketResponse>() {
        @Override
        public void onSuccess(GetBucketRequest request, GetBucketResponse response) {
            String requestId = response.getOpcRequestId();
            Bucket bucket = response.getBucket();
            System.out.println(requestId);
            System.out.println(bucket.getName());
        }

        @Override
        public void onError(GetBucketRequest request, Throwable error) {
            error.printStackTrace();
        }
};
 
Future<GetBucketResponse> future = client.getBucket(
        GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build(),
        handler);

L'SDK offre camerieri che consentono al codice di attendere fino a quando una risorsa specifica raggiunge lo stato desiderato. Un cameriere può essere richiamato sia in modo bloccante che non bloccante (con callback asincrono) e attenderà fino al raggiungimento dello stato desiderato o al superamento di un timeout. I camerieri astraggono la logica di polling che altrimenti dovresti scrivere in una chiamata a metodo singolo facile da usare.

I camerieri vengono ottenuti tramite il client del servizio (client.getWaiters()). Al metodo waiters.for<Resource> vengono passati sia uno stato Get<Resource>Request che uno stato del ciclo di vita desiderato. Ad esempio:

public static Instance waitForInstanceProvisioningToComplete(  ComputeClient computeClient, String instanceId) throws Exception {
        
    ComputeWaiters waiters = computeClient.getWaiters();
    GetInstanceResponse response = waiters.forInstance(
        GetInstanceRequest.builder().instanceId(instanceId).build(),
        Instance.LifecycleState.Running)
    .execute();
        
    return response.getInstance();
}

Ogni metodo waiters.for<Resource> dispone di due versioni:

• Una versione utilizza i valori di polling predefiniti. Ad esempio:

  waiters.forInstance(GetInstanceRequest, LifecycleState)

• L'altra versione ti dà il pieno controllo su quanto tempo aspettare e quanto tempo tra i tentativi di polling. Ad esempio:

  waiters.forInstance(GetInstanceRequest, LifecycleState, TerminationStrategy, DelayStrategy)

Un client diventa thread-safe quando viene inizializzato. Dopo aver impostato l'endpoint, è possibile utilizzare in modo sicuro un client in più thread e contemporaneamente richiamarvi metodi.

È possibile riutilizzare un client su più richieste, sia tra thread concorrenti che all'interno di un singolo thread. A meno che le risorse dell'ambiente non siano limitate, è necessario chiudere il client solo immediatamente prima che non rientri nell'ambito di applicazione.

Il servizio di storage degli oggetti supporta i caricamenti multiparte per semplificare i caricamenti di oggetti di grandi dimensioni suddividendo l'oggetto di grandi dimensioni in parti. L'SDK per Java supporta le operazioni di caricamento multiparte raw per casi d'uso avanzati, nonché una classe di caricamento di livello superiore che utilizza le API di caricamento multiparte. Utilizzo dei caricamenti multiparte fornisce collegamenti alle API utilizzate per le operazioni di caricamento multiparte. I caricamenti multiparte di livello superiore vengono implementati utilizzando UploadManager, che consente di suddividere un oggetto di grandi dimensioni in parti, caricare le parti in parallelo, quindi ricombinare e eseguire il commit delle parti come un singolo oggetto nello storage.

L'esempio UploadObject mostra come utilizzare UploadManager per suddividere automaticamente un oggetto in parti da caricare per semplificare l'interazione con il servizio di storage degli oggetti.

A partire dalla versione 2.10.0, l'SDK per Java è configurato per impostazione predefinita per riprovare a eseguire determinate operazioni SDK non riuscite. L'SDK consente di specificare la strategia da utilizzare per la modalità di gestione dei nuovi tentativi, incluso il numero di tentativi da eseguire, la condizione in base alla quale l'SDK deve riprovare a eseguire un'operazione e quando interrompere il nuovo tentativo di un'operazione. È possibile impostare questi parametri a livello di client e a livello di singola richiesta.

Per determinare quali operazioni del servizio hanno nuovi tentativi abilitati per impostazione predefinita, fare riferimento alla descrizione delle operazioni del servizio nell'SDK.

Per impostazione predefinita, l'SDK riproverà le operazioni con i codici di stato di risposta HTTP 409 (con un codice di errore IncorrectState), 429, 500, 502, 503, 504, errori di timeout (ad esempio connessione HTTP e timeout di lettura), errori di connessione delle richieste, eccezioni delle richieste e eccezioni degli interruttori di circuito.

La configurazione dei nuovi tentativi predefinita più recente e l'elenco degli errori che è possibile rieseguire possono essere visualizzati su Github.

Disabilitazione dei nuovi tentativi predefiniti

Per disattivare la funzione di nuovi tentativi predefinita, è possibile effettuare una delle seguenti operazioni:

1. Impostare la variabile di ambiente OCI_SDK_DEFAULT_RETRY_ENABLED su false per disabilitare i tentativi predefiniti a livello globale

2. Eseguire l'override dei tentativi predefiniti per un'istanza client specifica. Questo esempio mostra l'override dei nuovi tentativi predefiniti per objectStorageClient:

   ClientConfiguration clientConfiguration =
           ClientConfiguration.builder()
                   .retryConfiguration(RetryConfiguration.builder().terminationStrategy(new MaxAttemptsTerminationStrategy(1))
                           .build())
                   .build();

   ObjectStorage objectStorageClient = ObjectStorageClient.builder().configuration(clientConfiguration).build(provider);
   

3. Esegue l'override dei tentativi predefiniti per un'istanza di richiesta specifica. Questo esempio mostra i tentativi di sostituzione per putObjectRequest:

   PutObjectRequest putObjectRequest =
           PutObjectRequest.builder()
                   .putObjectBody(stream)
                   .bucketName(bucketName)
                   .objectName(objectName)
                   .namespaceName(namespace)
                   .retryConfiguration(RetryConfiguration.builder().terminationStrategy(new MaxAttemptsTerminationStrategy(1)).build())
                   .build();

Riprova precedenza comportamento

A partire dalla versione 2.10.0, l'SDK per Java fornisce il supporto predefinito per gli interruttori di circuito per i client di servizio che hanno abilitato gli interruttori di circuito SDK predefiniti. Gli interruttori di circuito aiutano a impedire al client di sovraccaricare il servizio bloccando l'invio delle richieste al servizio dopo il raggiungimento di una determinata soglia di errore.

Per gli interruttori di circuito predefiniti, tutti gli errori che possono essere ripetuti verranno trattati come errori per gli interruttori di circuito. Per determinare i client del servizio per i quali sono abilitati gli interruttori di circuito, fare riferimento alla descrizione del client del servizio nell'SDK.

Configurazione dell'interruttore

I seguenti parametri definiscono un interruttore:

Configurazione predefinita interruttore

Di seguito è riportata la configurazione predefinita dell'interruttore circuito.

Disabilitazione dell'interruttore di circuito predefinito

Per disattivare la funzione di interruttore predefinito, è possibile effettuare una delle operazioni riportate di seguito.

Priorità comportamento interruttore

Qualsiasi configurazione dell'interruttore di circuito definita in modo esplicito a livello di client sostituirà la configurazione dell'interruttore di circuito predefinito globale e l'override a livello di ambiente per tale client.

Per ulteriori informazioni sugli interruttori di circuito e sulla configurazione dell'interruttore di circuito predefinito, vedere questo esempio su Github.

Le richieste raw sono utili, e in alcuni casi necessarie. I casi d'uso tipici sono: quando si utilizza il proprio client HTTP, si effettua una richiesta autenticata da OCI a un endpoint alternativo e si effettua una richiesta a un'API OCI che non è attualmente supportata nell'SDK. L'SDK per Java espone la classe DefaultRequestSigner che è possibile utilizzare per creare un'istanza RequestSigner per richieste non standard.

L'esempio Richiesta raw in GitHub mostra come:

• creare un provider di autenticazione e richiedere il firmatario
• integrazione con un client HTTP (Jersey in questo esempio) per autenticare le richieste

Gli endpoint del servizio possono essere impostati in tre modi.

• Chiamare setEndpoint() nell'istanza del servizio. In questo modo è possibile specificare un nome host completo, ad esempio https://www.example.com.
• Chiamare setRegion() nell'istanza del servizio. In questo modo viene selezionato il nome host appropriato per il servizio per l'area specificata. Tuttavia, se il servizio non è supportato nell'area impostata, l'SDK per Java restituisce un errore.
• Passare l'area nel file di configurazione. Per ulteriori informazioni, vedere SDK and CLI Configuration File.

Tenere presente che non è possibile utilizzare un'istanza del servizio per comunicare con aree diverse. Se è necessario effettuare richieste in aree diverse, creare più istanze di servizio.

Se si dispone di una logica condizionale basata su un enum, assicurarsi che il codice gestisca il caso UnknownEnumValue per garantire la compatibilità in avanti. Alcuni campi di risposta sono di tipo enum, ma in futuro i singoli servizi potrebbero restituire valori non coperti da enum esistenti per quel campo. Per affrontare questa possibilità, ogni campo di risposta di tipo enum ha un valore aggiuntivo denominato UnknownEnumValue. Se un servizio restituisce un valore non riconosciuto dalla versione dell'SDK in uso, il campo di risposta verrà impostato su questo valore.

Se si utilizza una versione dell'SDK rilasciata prima dell'annuncio di una nuova area, è possibile utilizzare una soluzione alternativa per raggiungerla.

Un'area è un'area geografica localizzata. Per ulteriori informazioni sulle aree e su come identificarle, vedere Aree e domini di disponibilità.

Un realm è un set di aree che condividono entità. È possibile identificare il realm guardando il nome del dominio alla fine dell'indirizzo di rete. Ad esempio, il realm per xyz.abc.123.oraclecloud.com è oraclecloud.com.

È necessario prima chiamare Region.register per registrare la nuova area, quindi è possibile impostare l'area utilizzando il file di configurazione o chiamando il metodo setRegion.

AuthenticationDetailsProvider provider =
        new ConfigFileAuthenticationDetailsProvider(configurationFilePath, profile);

IdentityClient client = IdentityClient.builder()
        .endpoint("https://identity.ca-toronto-1.oraclecloud.com")
        .build(provider);

InstancePrincipalsAuthenticationDetailsProvider provider = InstancePrincipalsAuthenticationDetailsProvider.builder()
        .federationEndpoint("https://auth.ca-toronto-1.oraclecloud.com/v1/x509")
        .build();

IdentityClient identityClient = IdentityClient.builder()
        .endpoint("https://identity.ca-toronto-1.oraclecloud.com")
        .build(provider);

Alcune API restituiscono set di risultati impaginati, pertanto è necessario verificare la presenza di elementi aggiuntivi e, se necessario, recuperare la pagina successiva. Puoi farlo manualmente o puoi usare un iteratore.

ObjectStorage client = ...;
 
ListBucketsRequest.Builder builder =
    ListBucketsRequest.builder().namespaceName(namespace);
String nextPageToken = null;
do {
    builder.page(nextPageToken);
    ListBucketsResponse listResponse = client.listBuckets(builder.build());
    List<Bucket> buckets = listResponse.getItems();
    // handle buckets
    nextPageToken = listResponse.getOpcNextPage();
} while (nextPageToken != null);

Client Side Encryption consente di cifrare i dati sul lato client prima di memorizzarli localmente o utilizzarli con altri servizi Oracle Cloud Infrastructure.

Per utilizzare la cifratura lato client, è necessario creare una chiave di cifratura master (MEK) mediante il servizio Key Management. Questa operazione può essere eseguita utilizzando le operazioni CreateKey o ImportKey.

MEK viene utilizzato per generare una chiave di cifratura dati (DEK, Data Encryption Key) per cifrare ogni payload. Una copia crittografata di questo DEK (crittografato sotto il MEK) e altri pezzi di metadati sono inclusi nel payload cifrato restituito dagli SDK in modo che possano essere utilizzati per la decifrazione.

// String encryption example
			
final byte[] plainText = "Hello World".getBytes();
String masterKeyId = "OCID....";
Map<String, String> context = Collections.singletonMap("Example", "value");
 
OciCrypto ociCrypto = new OciCrypto();
KmsMasterKey kmsMasterKey = new KmsMasterKey(authenticationProvider, Region.US_ASHBURN_1.getRegionId(), vaultId, masterKeyId);
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(kmsMasterKey);
 
//  Encrypt the data and embed the master key ID in the header
final OciCryptoResult encryptResult = ociCrypto.encryptData(kmsMasterKeyProvider, plainText, context);
final byte[] cipherText = encryptResult.getResult();
 
//  Decrypt the data
final OciCryptoResult decryptResult = ociCrypto.decryptData(kmsMasterKeyProvider, cipherText);

// Create Encryption file stream
FileInputStream in = new FileInputStream(srcFile);
OciCrypto ociCrypto = new OciCrypto();
KmsMasterKey kmsMasterKey = new KmsMasterKey(authenticationProvider, Region.US_ASHBURN_1.getRegionId(), vaultId, masterKeyId);
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(kmsMasterKey);
OciCryptoInputStream encryptingStream = ociCrypto.createEncryptingStream(kmsMasterKeyProvider, in);
 
// Write the encrypted data to file
FileOutputStream out = new FileOutputStream(srcFile + ".encrypted");
IOUtils.copy(encryptingStream, out);
encryptingStream.close();
out.close();
 
// For decryption, no need to pass key info
KmsMasterKeyProvider kmsMasterKeyProvider = new KmsMasterKeyProvider(authenticationProvider);
// Create the Decryption file stream.
in = new FileInputStream(srcFile + ".encrypted");
OciCryptoInputStream decryptingStream = ociCrypto.createDecryptingStream(kmsMasterKeyProvider, in);
 
 
// Return the plaintext data
out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
out.close();

Quando si gestisce un'eccezione, è possibile ottenere ulteriori informazioni sulla richiesta HTTP che l'ha causata, ad esempio il codice di stato o il timeout. È inoltre possibile ottenere l'ID della richiesta quando si gestisce un BmcException utilizzando il metodo getOpcRequestId.

Questo esempio mostra un blocco try-catch che gestisce un BmcExceptione stampa l'ID della richiesta.

ObjectStorage client = ...;
try {
    GetBucketResponse response = client.getBucket(
	        GetBucketRequest.builder().namespaceName("myNamespace").bucketName("myBucket").build());
    String requestId = response.getOpcRequestId();
    System.out.println(requestId);
} catch (BmcException e) {
    String requestId = e.getOpcRequestId();
    System.out.println(requestId);
    e.printStackTrace();
}

Le eccezioni nell'SDK per Java sono eccezioni runtime (non selezionate), pertanto non vengono visualizzate nelle firme dei metodi. Tutte le API possono generare un BmcException.