Guida introduttiva

Questo argomento descrive come installare e configurare l'SDK Oracle Cloud Infrastructure per Java.

Suggerimento

L'SDK per Java è preconfigurato con le credenziali e pronto per l'uso immediatamente dall'interno di Cloud Shell. Per ulteriori informazioni sull'uso dell'SDK per Java dall'interno di Cloud Shell, vedere SDK per Java Cloud Shell Quick Start.

Installazione con Resource Manager

Puoi utilizzare Resource Manager per installare Oracle Cloud Development Kit su un'istanza di computazione nel tuo compartimento. Il kit di sviluppo Oracle Cloud include l'SDK per Java e altri strumenti di sviluppo Oracle.

Download dell'SDK da GitHub

È possibile scaricare l'SDK per Java come archivio zip da GitHub. Contiene l'SDK, tutte le sue dipendenze, documentazione ed esempi. Per garantire la massima compatibilità ed evitare problemi, usare la versione delle dipendenze incluse nell'archivio. Alcuni problemi importanti sono:

Bouncy Castle: L'SDK raggruppa 1.60 (incluso in questa distribuzione). Se è necessaria la conformità agli standard FIPS, vedere Uso di BC-FIPS anziché Bouncy Castle.
Jersey Core e Client: l'SDK raggruppa la versione 2.24.1, necessaria per supportare i caricamenti di oggetti di grandi dimensioni nello storage degli oggetti. Le versioni precedenti non supporteranno caricamenti superiori a ~2,1 GB.
API Jax-RS: l'SDK raggruppa 2.0.1 delle specifiche. Le versioni precedenti causano problemi.

Nota

L'SDK per Java è fornito in bundle con Jersey (incluso in questa distribuzione), ma è anche possibile utilizzare la propria implementazione JAX-RS. Per i dettagli, vedere Utilizzo dell'implementazione JAX-RS personale

Download dell'SDK da Maven o JCenter

Maven Central e

JCenter.

Installazione con yum

Se stai utilizzando Oracle Linux 7 o 8, puoi utilizzare yum per installare l'SDK OCI per Java.

Per Oracle Linux 7:

sudo yum-config-manager --enable ol7_developer
sudo yum install java-oci-sdk

Per Oracle Linux 8:

sudo yum-config-manager --enable ol8_developer
sudo yum install java-oci-sdk

Il file jar OCI si troverà in:/usr/lib64/java-oci-sdk/lib/oci-java-sdk-full-<version>.jar e le librerie di terze parti saranno in /usr/lib64/java-oci-sdk/third-party/lib.

È possibile aggiungere le voci seguenti al classpath: /usr/lib64/java-oci-sdk/lib/oci-java-sdk-full-<version>.jar:/usr/lib64/java-oci-sdk/third-party/lib/* Ad esempio:

javac -cp "/usr/lib64/java-oci-sdk/third-party/lib/*:/usr/lib64/java-oci-sdk/lib/oci-java-sdk-full-1.8.2.jar" MyFile.java

Configurazione dell'SDK

I servizi SDK richiedono due tipi di configurazione: le credenziali e le impostazioni HTTP lato client.

Configurazione delle credenziali

In primo luogo, è necessario impostare le credenziali e il file di configurazione. Per istruzioni, vedere SDK and CLI Configuration File.

Successivamente è necessario configurare il client in modo che utilizzi le credenziali. Le credenziali vengono astratte mediante un'interfaccia AuthenticationDetailsProvider. I clienti possono implementare questo come si sceglie. Abbiamo incluso una semplice classe POJO/builder per aiutare con questo task (SimpleAuthenticationDetailsProvider).

È possibile caricare una configurazione con o senza un profilo:

ConfigFile config 
    = ConfigFileReader.parse("~/.oci/config");
ConfigFile configWithProfile 
    = ConfigFileReader.parse("~/.oci/config", "DEFAULT");

Il fornitore di chiavi private può essere creato direttamente con il percorso file oppure utilizzando il file di configurazione:

Supplier<InputStream> privateKeySupplier 
    = new SimplePrivateKeySupplier("~/.oci/oci_api_key.pem");
Supplier<InputStream> privateKeySupplierFromConfigEntry 
    = new SimplePrivateKeySupplier(config.get("key_file"));

Per creare un provider di autenticazione utilizzando la Costruzione guidata:

AuthenticationDetailsProvider provider 
    = SimpleAuthenticationDetailsProvider.builder()
        .tenantId("myTenantId")
        .userId("myUserId")
        .fingerprint("myFingerprint")
        .privateKeySupplier(privateKeySupplier)
        .build();

Per creare un provider di autenticazione utilizzando la Costruzione guidata con un file di configurazione:

AuthenticationDetailsProvider provider 
    = SimpleAuthenticationDetailsProvider.builder()
        .tenantId(config.get("tenancy"))
        .userId(config.get("user"))
        .fingerprint(config.get("fingerprint"))
        .privateKeySupplier(privateKeySupplier)
        .build();

Infine, se si utilizzano le chiavi dei file di configurazione standard e la posizione dei file di configurazione standard, è possibile semplificare ulteriormente utilizzando ConfigFileAuthenticationDetailsProvider:
```
AuthenticationDetailsProvider provider 
    = new ConfigFileAuthenticationDetailsProvider("ADMIN_USER");
```

Configurazione delle opzioni lato client

Creare una configurazione lato client tramite la classe ClientConfiguration. Se non si fornisce una configurazione personalizzata, l'SDK per Java utilizza una configurazione predefinita. Per fornire una configurazione personalizzata, utilizzare quanto segue:

ClientConfiguration clientConfig 
    = ClientConfiguration.builder()
        .connectionTimeoutMillis(3000)
        .readTimeoutMillis(60000)
        .build();

Dopo aver eseguito sia la configurazione delle credenziali che la configurazione client facoltativa, è possibile avviare la creazione delle istanze di servizio.

Per un esempio di codice che illustra come impostare e utilizzare i timeout di connessione e lettura nella configurazione del client, vedere l'esempio di timeout configurazione client in GitHub.

Configurazione delle opzioni personalizzate

Nel file di configurazione è possibile inserire coppie chiave-valore personalizzate definite, quindi fare riferimento a tali coppie in base alle esigenze. Ad esempio, è possibile specificare un ID compartimento utilizzato di frequente nel file di configurazione:

[DEFAULT]
user=ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcmdy5eqbb6qt2jvpkanghtgdaqedqw3rynjq
fingerprint=20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>


custom_compartment_id=ocid1.compartment.oc1..<unique_ID>

Quindi è possibile recuperare il valore:

ConfigFile config 
    = ConfigFileReader.parse("~/.oci/config");

String compartmentId = config.get("custom_compartment_id");

Utilizzo dell'SDK per Java

Esistono due modi per utilizzare l'SDK Oracle Cloud Infrastructure per Java nel tuo progetto.

Importare oci-java-sdk-bom, seguito dalla libreria client HTTP e dalle dipendenze del progetto.

La libreria client HTTP è configurabile e non viene scelta alcuna libreria per impostazione predefinita. L'SDK OCI per Java attualmente offre le seguenti librerie client HTTP tra cui scegliere:

Jakarta EE 8/Jersey 2 - oci-common-httpclient-jersey
Jakarta EE 9/Jersey 3 - oci-common-httpclient-jersey3

È necessario scegliere in modo esplicito la libreria dichiarando una dipendenza in oci-java-sdk-common-httpclient-jersey o oci-java-sdk-common-httpclient-jersey3. Ad esempio:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.oracle.oci.sdk</groupId>
      <artifactId>oci-java-sdk-bom</artifactId>
      <!-- replace the version below with your required version -->
      <version>3.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <!-- Since this is the "application" pom.xml, choose the httpclient to use. -->
    <groupId>com.oracle.oci.sdk</groupId>
    <artifactId>oci-java-sdk-common-httpclient-jersey</artifactId>
  </dependency>
  <dependency>
    <groupId>com.oracle.oci.sdk</groupId>
    <artifactId>oci-java-sdk-audit</artifactId>
  </dependency>
  <dependency>
    <groupId>com.oracle.oci.sdk</groupId>
    <artifactId>oci-java-sdk-core</artifactId>
  </dependency>
  <dependency>
    <groupId>com.oracle.oci.sdk</groupId>
    <artifactId>oci-java-sdk-database</artifactId>
  </dependency>
  <!-- more dependencies if needed -->
</dependencies>

Aggiungere la dipendenza ombreggiata oci-java-sdk-shaded-full al file pom. È possibile utilizzare la dipendenza ombreggiata per includere tutte le classi di terze parti e le relative dipendenze transitive rinominandole e includendole nel progetto. Contiene un Uber JAR, che è fondamentalmente una combinazione di più JAR. Tutti i pacchetti all'interno del JAR Uber vengono rinominati. Ciò eviterà conflitti tra le dipendenze dell'SDK di Oracle Cloud Infrastructure e le dipendenze di terze parti che potresti utilizzare nel tuo progetto.

Ad esempio, le classi in org.apache.commons vengono riposizionate in shaded.com.oracle.oci.javasdk.org.apache.commons.

I contenuti di Uber JAR sono i seguenti:
```
shaded/com/oracle/oci/javasdk/org/apache/commons/codec/BinaryDecoder.class
shaded/com/oracle/oci/javasdk/org/apache/commons/logging/LogFactory.class
```
Se si utilizza Maven per gestire le dipendenze, è possibile trovare la dipendenza ombreggiata più recente nel repository Maven.

Aggiungere l'ultima versione di oci-java-sdk-shaded-full alle dipendenze:
```
<dependency>
  <groupId>com.oracle.oci.sdk</groupId>
  <artifactId>oci-java-sdk-shaded-full</artifactId>
  
  <version>3.0.0</version>
<dependency>
```

Documentazione dell'infrastruttura Oracle Cloud