Konzepte

Um synchrone Aufrufe durchzuführen, erstellen Sie eine Instanz des synchronen Clients. Das allgemeine Muster für synchrone Clients sieht wie folgt aus: Für einen Service mit dem Namen Example gibt es eine Schnittstelle mit dem Namen ExampleService, und die Implementierung des synchronen Clients wird als ExampleServiceClient bezeichnet. Im Folgenden finden Sie ein Beispiel für das Erstellen eines Object Storage-Clients:

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);

Synchrone Aufrufe werden blockiert, bis die Antwort verfügbar ist. Alle SDK-APIs geben ein Antwortobjekt zurück (unabhängig davon, ob die API Inhalt zurücksendet oder nicht). Das Antwortobjekt enthält im Allgemeinen mindestens eine Anforderungs-ID, die Sie beim Kontaktieren von Oracle Support angeben können, um Hilfe zu einer bestimmten Anforderung zu erhalten.

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());

Um asynchrone Aufrufe durchzuführen, erstellen Sie eine Instanz des asynchronen Clients. Das allgemeine Muster für asynchrone Clients sieht wie folgt aus: Für einen Service mit dem Namen Example gibt es eine Schnittstelle mit dem Namen ExampleServiceAsync, und die Implementierung des asynchronen Clients wird als ExampleServiceAsyncClient bezeichnet. Im Folgenden finden Sie ein Beispiel für das Erstellen eines Object Storage-Clients:

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);

Asynchrone Aufrufe werden sofort zurückgegeben. Sie müssen einen AsyncHandler angeben, der aufgerufen wird, nachdem der Aufruf entweder erfolgreich oder nicht erfolgreich abgeschlossen wurde:

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);

Das SDK bietet Wartende, mit denen Ihr Code warten kann, bis eine bestimmte Ressource den gewünschten Status erreicht. Ein Wartender kann sowohl blockierend als auch nicht blockierend (mit asynchronem Callback) aufgerufen werden und wartet, bis der gewünschte Status erreicht oder ein Timeout überschritten wird. Wartende abstrahieren die Polling-Logik, die Sie sonst in einen benutzerfreundlichen einzelnen Methodenaufruf schreiben müssten.

Wartende werden über den Serviceclient abgerufen (client.getWaiters()). Sowohl eine Get<Resource>Request-Anforderung als auch der gewünschte Lebenszyklusstatus werden an die Methode waiters.for<Resource> übergeben. Beispiel:

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();
}

Jede waiters.for<Resource>-Methode hat zwei Versionen:

• Eine Version nutzt die Standard-Polling-Werte. Beispiel:

  waiters.forInstance(GetInstanceRequest, LifecycleState)

• Die andere Version bietet Ihnen volle Kontrolle über die Wartezeit und die Zeit zwischen Polling-Versuchen. Beispiel:

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

Ein Client wird bei der Initialisierung threadsicher. Nachdem Sie den Endpunkt festgelegt haben, können Sie einen Client sicher in mehreren Threads und nebenläufig in Aufrufmethoden verwenden.

Sie können einen Client in mehreren Anforderungen sowohl über nebenläufige Threads als auch innerhalb eines einzelnen Threads wiederverwenden. Wenn die Ressourcen der Umgebung nicht eingeschränkt sind, sollten Sie den Client erst kurz vor Überschreiten des Geltungsbereichs schließen.

Der Object Storage-Service unterstützt Multipart-Uploads, um Large-Object-Uploads zu vereinfachen, indem das Large Object in Teile aufgeteilt wird. Das SDK für Java unterstützt Raw-Vorgänge für mehrteilige Uploads für erweiterte Anwendungsfälle sowie eine Uploadklasse auf höherer Ebene, die die APIs für Multipart-Uploads verwendet. Unter Mehrteilige Uploads verwenden finden Sie Links zu den APIs, die für mehrteilige Uploadvorgänge verwendet werden. Multipart-Uploads auf höherer Ebene werden mit UploadManager implementiert. Dabei wird ein Large Object für Sie in Teile aufgeteilt, und die Teile werden parallel hochgeladen und dann wieder zusammengesetzt, sodass die Teile als einzelnes Objekt im Speicher festgeschrieben werden.

Das Beispiel UploadObject zeigt, wie mit UploadManager ein Objekt für den Upload automatisch aufgeteilt wird, um die Interaktion mit dem Object Storage-Service zu vereinfachen.

Ab Version 2.10.0 ist das SDK für Java standardmäßig so konfiguriert, dass bestimmte nicht erfolgreiche SDK-Vorgänge wiederholt werden. Mit dem SDK können Sie die Strategie für Wiederholungen angeben, einschließlich der Anzahl der Wiederholungsversuche, der Bedingung, unter der das SDK einen Vorgang wiederholen soll, und wann die Wiederholung eines Vorgangs gestoppt werden soll. Sie können diese Parameter auf Clientebene und auf individueller Anforderungsebene festlegen.

Um zu bestimmen, für welche Servicevorgänge standardmäßig Wiederholungen aktiviert sind, lesen Sie die Beschreibung der Servicevorgänge im SDK.

Standardmäßig wiederholt das SDK Vorgänge mit HTTP-Antwortstatuscodes 409 (mit einem IncorrectState-Fehlercode), 429, 500, 502, 503, 504, Timeoutfehlern (wie HTTP-Verbindungs- und Lesetimeouts), Verbindungsanforderungsfehlern, Anforderungsausnahmen und Circuit-Breaker-Ausnahmen.

Die aktuelle Standardwiederholungskonfiguration und die Liste der wiederholbaren Fehler finden Sie auf GitHub.

Standardwiederholungen deaktivieren

Um ein Opt-out aus dem Standardwiederholungsfeature vorzunehmen, können Sie einen der folgenden Schritte ausführen:

1. Setzen Sie die Umgebungsvariable OCI_SDK_DEFAULT_RETRY_ENABLED auf false, um die Standardwiederholungen global zu deaktivieren.

2. Setzen Sie die Standardwiederholungen für eine bestimmte Clientinstanz außer Kraft. Dieses Beispiel zeigt, wie die Standardwiederholungen für objectStorageClient außer Kraft gesetzt werden:

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

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

3. Setzen Sie Standardwiederholungen für eine bestimmte Anforderungsinstanz außer Kraft. Dieses Beispiel zeigt, wie Wiederholungen für putObjectRequest außer Kraft gesetzt werden:

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

Priorität für Wiederholungsverhalten

Ab Version 2.10.0 bietet das SDK für Java Standardunterstützung für Circuit Breaker für Serviceclients, bei denen Standard-SDK-Circuit-Breaker aktiviert sind. Circuit Breaker verhindern, dass der Client den Service überlastet, indem sie Anforderungen an den Service blockieren, nachdem ein bestimmter Fehlerschwellenwert erreicht wurde.

Bei Standard-Circuit-Breakern werden alle wiederholbaren Fehler als Fehler für die Circuit Breaker behandelt. Informationen zum Bestimmen, für welche Serviceclients Circuit Breaker aktiviert sind, finden Sie in der Beschreibung des Serviceclients im SDK.

Circuit-Breaker-Konfiguration

Die folgenden Parameter definieren einen Circuit Breaker:

Circuit-Breaker-Standardkonfiguration

Die Circuit-Breaker-Standardkonfiguration lautet wie folgt:

Standard-Circuit-Breaker deaktivieren

Um ein Opt-out aus dem Circuit-Breaker-Standardfeature vorzunehmen, können Sie einen der folgenden Schritte ausführen:

Prioritätsfolge des Circuit-Breaker-Verhaltens

Jede explizit auf Clientebene definierte Circuit-Breaker-Konfiguration setzt die globale Circuit-Breaker-Konfiguration und den Override auf Umgebungsebene für den betreffenden Client außer Kraft.

Weitere Informationen zu Circuit Breakern und zur Circuit-Breaker-Standardkonfiguration finden Sie in diesem Beispiel auf GitHub.

Raw-Anforderungen sind nützlich und in einigen Fällen erforderlich. Typische Anwendungsfälle sind die Verwendung Ihres eigenen HTTP-Clients, die Durchführung einer OCI-authentifizierten Anforderung an einen alternativen Endpunkt und die Durchführung einer Anforderung an eine OCI-API, die aktuell im SDK nicht unterstützt wird. Das SDK für Java zeigt die Klasse DefaultRequestSigner an, mit der Sie eine RequestSigner-Instanz für Nicht-Standardanforderungen erstellen können.

Das Beispiel für Raw-Anforderungen auf GitHub zeigt, wie Sie Folgendes durchführen:

• Authentifizierungsprovider erstellen und Signaturgeber anfordern
• Integration mit einem HTTP-Client (in diesem Beispiel Jersey) durchführen, um Anforderungen zu authentifizieren

Serviceendpunkte können auf drei Arten festgelegt werden.

• Rufen Sie setEndpoint() in der Serviceinstanz auf. Auf diese Weise können Sie einen vollständigen Hostnamen angeben (z.B. https://www.example.com).
• Rufen Sie setRegion() in der Serviceinstanz auf. Dadurch wird der entsprechende Hostname für den Service für die angegebene Region ausgewählt. Wenn der Service jedoch in der von Ihnen festgelegten Region nicht unterstützt wird, gibt das SDK für Java einen Fehler zurück.
• Übergeben Sie die Region in der Konfigurationsdatei. Weitere Informationen finden Sie unter SDK- und CLI-Konfigurationsdatei.

Beachten Sie, dass eine Serviceinstanz nicht zur Kommunikation mit verschiedenen Regionen verwendet werden kann. Wenn Sie Anforderungen an verschiedene Regionen durchführen müssen, erstellen Sie mehrere Serviceinstanzen.

Wenn Sie über eine bedingte Logik basierend auf einem enum verfügen, stellen Sie sicher, dass Ihr Code den Fall UnknownEnumValue verarbeitet, um die Aufwärtskompatibilität zu gewährleisten. Einige Antwortfelder haben den Typ "enum", in Zukunft geben aber möglicherweise einzelne Services Werte zurück, die nicht durch vorhandene enums für dieses Feld abgedeckt sind. Aus diesem Grund hat jedes Antwortfeld vom Typ "enum" einen zusätzlichen Wert mit dem Namen UnknownEnumValue. Wenn ein Service einen Wert zurückgibt, der von Ihrer SDK-Version nicht erkannt wird, wird das Antwortfeld auf diesen Wert gesetzt.

Wenn Sie eine SDK-Version verwenden, die vor der Ankündigung einer neuen Region veröffentlicht wurde, können Sie diese mit einem Workaround erreichen.

Eine Region ist ein lokalisierter geografischer Bereich. Weitere Informationen zu Regionen und deren Identifizierung finden Sie unter Regionen und Availability-Domains.

Eine Realm besteht aus einer Reihe von Regionen, die gemeinsame Entitys haben. Sie können Ihre Realm identifizieren, indem Sie sich den Domainnamen am Ende der Netzwerkadresse ansehen. Beispiel: Die Realm für xyz.abc.123.oraclecloud.com ist oraclecloud.com.

Sie müssen zunächst Region.register aufrufen, um die neue Region zu registrieren. Anschließend können Sie die Region entweder mit der Konfigurationsdatei oder durch Aufrufen der Methode setRegion festlegen.

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);

Einige APIs geben paginierte Ergebnismengen zurück. Sie müssen also nach zusätzlichen Elementen suchen und bei Bedarf die nächste Seite abrufen. Dies kann manuell geschehen, oder Sie können einen Iterator verwenden.

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);

Mit der clientseitigen Verschlüsselung können Sie Daten auf Clientseite verschlüsseln, bevor Sie sie lokal speichern oder mit anderen Oracle Cloud Infrastructure-Services verwenden.

Um die clientseitige Verschlüsselung zu verwenden, müssen Sie einen Masterverschlüsselungsschlüssel (Master Encryption Key, MEK) mit dem Key Management-Service erstellen. Dies kann mit CreateKey - oder ImportKey-Vorgängen geschehen.

Mit dem MEK wird ein Datenverschlüsselungsschlüssel (Data Encryption Key, DEK) generiert, um jede Payload zu verschlüsseln. Eine verschlüsselte Kopie dieses DEK (mit dem MEK verschlüsselt) und andere Metadaten werden in die verschlüsselte Payload aufgenommen, die von den SDKs zurückgegeben wird, damit sie zur Entschlüsselung verwendet werden können.

// 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();

Bei der Verarbeitung einer Ausnahme können Sie weitere Informationen zu der HTTP-Anforderung erhalten, die diese verursacht hat, wie Statuscode oder Timeout. Sie können die Anforderungs-ID auch bei der Verarbeitung einer BmcException mit der Methode getOpcRequestId abrufen.

Dieses Beispiel zeigt einen Try-Catch-Block, der eine BmcException verarbeitet und die Anforderungs-ID ausgibt.

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();
}

Ausnahmen im SDK für Java sind Laufzeitausnahmen (ungeprüft), sodass sie nicht in Methodensignaturen angezeigt werden. Alle APIs können eine BmcException auslösen.