Hinweis:

Oracle Cloud Infrastructure-REST-APIs programmgesteuert mit Shell und Java-Code verwalten

Einführung

Oracle Cloud Infrastructure (OCI) bietet Kunden eine Cloud-Infrastruktur zum Hosten ihrer geschäftskritischen Anwendungen in der Cloud. OCI bietet Kunden auch die Möglichkeit, über die Konsole oder über APIs auf OCI-Services zuzugreifen. Für die Verbindung über APIs können Kunden SDKs basierend auf der Programmiersprache ihrer Wahl verwenden, wie Java, Python oder Ruby. Es gibt jedoch nur wenige Fälle, in denen der Kunde SDK nicht verwenden kann und keine Programmiersprache verwenden kann, sondern stattdessen eine direkte Verbindung über APIs über ein Tool, eine Datenbank oder eine Drittanbieteranwendung herstellen möchte, in der er das SDK nicht installieren kann. Hier ist die Verwendung von REST-APIs praktisch. Kunden können die von OCI bereitgestellten REST-APIs für fast alle Services nutzen und sie direkt in ihren Tools verwenden, indem sie einfach die Endpunkte aktualisieren und sich um Autorisierung und Authentifizierung kümmern.

Heutzutage möchte jedes Unternehmen die Leistungsfähigkeit von REST-APIs in seinen Anwendungen nutzen und ein innovatives Angebot für seine Kunden erstellen, ohne ein SDK installieren und verwalten zu müssen.

In diesem Tutorial werden wir besprechen und verstehen, wie OCI Unternehmen auf der ganzen Welt helfen kann, die Leistungsfähigkeit von REST-APIs mit OCI zu nutzen. In diesem Tutorial wird ein Beispiel für REST-APIs gezeigt, die auf Shellskripting und Java-Code basieren.

Ziele

Voraussetzungen

Aufgabe 1: Oracle Cloud Infrastructure-API-Schlüssel einrichten

  1. Melden Sie sich beim OCI-Mandanten mit dem Serviceaccount oder dem Admin-Benutzer an, und gehen Sie zu den Benutzereinstellungen.

    Benutzereinstellungen öffnen

    Oder

    Gehen Sie über die OCI-IAM-Konsole zum Benutzer. Stellen Sie sicher, dass der Benutzer über den erforderlichen Zugriff zum Erstellen und Aktualisieren der Infrastruktur auf OCI verfügt.

  2. Gehen Sie zum Abschnitt Ressourcen, und klicken Sie auf API-Schlüssel und API-Schlüssel hinzufügen. Wählen Sie diese Option aus, um den neuen Public Key und den neuen Private Key herunterzuladen, den Public Key hochzuladen oder den Public Key einzufügen.

    API-Schlüssel hinzufügen

  3. Speichern Sie die Schlüssel an einem geeigneten Speicherort, und speichern Sie die Konfigurationsdatei wie auf der folgenden Seite gezeigt. Sie benötigen diese Konfigurationsdatei und diesen Private Key, wenn Sie mit REST-APIs eine Verbindung zu Ihrem Mandanten herstellen.

    Konfigurationsdatei speichern

    Hinweis:

    • Sie benötigen dieselbe configuration parameters, um eine Verbindung zu Ihrer OCI-Region und Ihrem OCI-Mandanten herzustellen. Sie ersetzen die Parameter in Java-Code und Shell-Skripten entsprechend, während Sie tiefer in das Tutorial eintauchen.

    • Um OCI-Services von OCI Compute-Instanzen aufzurufen, bietet OCI eine sicherere Möglichkeit, Instanz-Principals zu verwenden. Verwenden Sie keine Benutzer-API-Schlüssel als Best Practices. Weitere Informationen finden Sie unter Services aus einer Instanz aufrufen.

Aufgabe 2: Shellskript zum Hochladen oder Einfügen einer Binärdatei aus OCI Object Storage mit REST-APIs erstellen und ausführen

  1. Wechseln Sie zum Dateisystem, und erstellen Sie eine Shell-Datei. In diesem Beispiel lautet der Dateiname PUT_OBJECT_REST_API.sh.

  2. Öffnen Sie die Datei mit einem beliebigen Editor, und fügen Sie den folgenden Code in die Shell-Datei ein.

    • PUT_OBJECT_REST_API.sh:

      #!/bin/bash

########################## Fill these in with your values ##########################
#OCID of the tenancy calls are being made in to
tenancy_ocid="ocid1.tenancy.oc1..aaaaaaaackopa"

# namespace of the tenancy
namespace="ocitenancyname"

# OCID of the user making the rest call
user_ocid="ocid1.user.oc1..aaaaaaaafelqsoffcjh"

# path to the private PEM format key for this user
privateKeyPath="/home/lovelesh/.oci/oci_api_key.pem"

# fingerprint of the private key for this user
fingerprint="72:d4:6c:f8:89"

#bucket name for uplaod/ put
bucket="ocibucketname"

#file name for upload/ put
object="test_pdf.pdf"

# The REST api you want to call, with any required paramters.
rest_api="/n/$namespace/b/$bucket/o/$object"

# The host you want to make the call against
host="objectstorage.us-ashburn-1.oraclecloud.com"

# the file containing the data you want to POST to the rest endpoint
body="/home/lovelesh/.oci/test_pdf.pdf"
####################################################################################

# extra headers required for a POST/PUT request
method="put"
content_type="application/octet-stream"
body_arg=(--data-binary @${body})
content_sha256="$(openssl dgst -binary -sha256 < $body | openssl enc -e -base64)";
content_sha256_header="x-content-sha256: $content_sha256"
content_length="$(wc -c < $body | xargs)";
content_length_header="content-length: $content_length"
headers="(request-target) date host"
# add on the extra fields required for a POST/PUT
headers=$headers" x-content-sha256 content-type content-length"
content_type_header="content-type: $content_type";

date=`date -u "+%a, %d %h %Y %H:%M:%S GMT"`
date_header="date: $date"
host_header="host: $host"
request_target="(request-target): $method $rest_api"

# note the order of items. The order in the signing_string matches the order in the headers, including the extra POST fields
signing_string="$request_target\n$date_header\n$host_header"
# add on the extra fields required for a POST/PUT
signing_string="$signing_string\n$content_sha256_header\n$content_type_header\n$content_length_header"



signature=`printf '%b' "$signing_string" | openssl dgst -sha256 -sign $privateKeyPath | openssl enc -e -base64 | tr -d '\n'`

set -x
curl -v -X $(echo $method | tr [:lower:] [:upper:]) --data-binary "@$body" -sS https://$host$rest_api -H "date: $date" -H "x-content-sha256: $content_sha256" -H "content-type: $content_type" -H "content-length: $content_length" -H "Authorization: Signature version=\"1\",keyId=\"$tenancy_ocid/$user_ocid/$fingerprint\",algorithm=\"rsa-sha256\",headers=\"$headers\",signature=\"$signature\""

  3. Jetzt haben wir den gesamten Code in die Shell-Datei eingefügt, lassen Sie uns daran arbeiten, die erforderlichen Werte zu aktualisieren und ihre Funktionalität zu verstehen.

    tenancy_ocid="ocid1.tenancy.oc1..aaaaaaaackopa"
...
fingerprint="72:d4:6c:f8:89"

    Alle diese Werte sind für eine sichere Verbindung zu Ihrem OCI-Mandanten verantwortlich. Rufen Sie diese Werte aus der Konfigurationsdatei ab.

    rest_api="/n/$namespace/b/$bucket/o/$object"
host="objectstorage.us-ashburn-1.oraclecloud.com"

    Dies ist der Endpunkt rest_api und der Endpunkt host. Bereiten Sie ihn entsprechend Ihrer Anforderung vor, da sich dies für jeden Service ändert. Das hier gezeigte Beispiel ist der Endpunkt für OCI Object Storage Service für die Ashburn-Region.

    headers=$headers" x-content-sha256 content-type content-length"
content_type_header="content-type: $content_type";
date=`date -u "+%a, %d %h %Y %H:%M:%S GMT"`
date_header="date: $date"
host_header="host: $host"
request_target="(request-target): $method $rest_api"

    Hier haben wir die Header für die REST-API zusammen mit dem Inhaltstyp und anderen erforderlichen Parametern erstellt. Beachten Sie, dass hier Definitionen für method_type, date und host header vorhanden sind, da für den Post Call ein detailliertes Headerset erforderlich ist.

    signing_string="$signing_string\n$content_sha256_header\n$content_type_header\n$content_length_header"
curl -v -X $(echo $method | tr [:lower:] [:upper:]) --data-binary "@$body" ...

    Schließlich erstellen wir die Signaturzeichenfolge und führen dann den REST-API-Aufruf mit curl aus. Beachten Sie, dass OCI die API-Aufrufe signieren muss. Deshalb tun wir dies hier.

  4. Nachdem Sie die Werte gemäß Ihrer Konfiguration aktualisiert haben, führen Sie das Shellskript aus. Es sollte angezeigt werden, dass das Skript alles gut ausführt, und die Datei wird an OCI Object Storage übertragen.

    Hinweis:

    • Stellen Sie sicher, dass Sie die Shell-Dateiberechtigung auf eine ausführbare Datei aktualisiert haben, indem Sie sie auf 755 ändern oder selbst verwalten.

    • Sie können dies auch unter Windows mit Powershell tun oder dasselbe Skript unter Windows verwenden, indem Sie ein WSL (Windows-Subsystem für Linux) wie Ubuntu installieren und es unter Windows von Ubuntu WSL ausführen. Weitere Informationen finden Sie unter Windows-Subsystem für Linux.

Aufgabe 3: Java-Code zum Hochladen oder Einfügen einer Binärdatei aus OCI Object Storage mit REST-APIs erstellen und ausführen

  1. Gehen Sie zu dem Dateisystem, und erstellen Sie eine JAVA-Datei. In diesem Beispiel lautet der Dateiname PUT_OBJECT_REST_API.java.

  2. Öffnen Sie die Datei mit einem beliebigen Editor, und fügen Sie den folgenden Code in die Shell-Datei ein.

    • PUT_OBJECT_REST_API.java:

      import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyFactory;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.Signature;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.PKCS8EncodedKeySpec;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Base64;

// NOTE - Feel free to remove logging as needed. Currently logs the signing string, host, date, and response. 

public class PUT_OBJECT_REST_API {

    private static final String apiKeyFilePath = "C:\\Users\\User1\\Folder\\privatekey.pem"
    private static final String tenancyId = "ocid1.tenancy.oc1..aaaaaaaackopa27emaz4uteg4q7"; // OCI Tenancy ID
    private static final String userId = "ocid1.user.oc1..aaaaaaaafelqsoffcjq"; // OCI User ID
    private static final String keyFingerprint = "72:d4:6c:f8:89:74:aa"; // OCI fingerprint
    private static final String region = "us-ashburn-1"; // OCI Region
    private static final String namespace = "ocitenancyname"; // OCI bucket namespace
    private static final String bucketName = "ocibucketname"; // OCI bucket NAME

    public static void main(String[] args) {
        try {
            String filePath = "D:\\file\\location\\test_pdf.pdf"; //args.length > 0 ? args[0] : ""; // File to upload (path)
            PrivateKey privateKey = loadPrivateKey(apiKeyFilePath);
            String fileName = Paths.get(filePath).getFileName().toString();
            String targetUri = "https://objectstorage." + region + ".oraclecloud.com/n/" + namespace + "/b/" + bucketName + "/o/" + fileName;
            HttpRequest request = buildRequest(targetUri, filePath, privateKey);
            HttpClient client = HttpClient.newHttpClient();
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            System.out.println("Response status code: " + response.statusCode());
            System.out.println("Response body: " + response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static PrivateKey loadPrivateKey(String filePath) throws IOException, NoSuchAlgorithmException, InvalidKeySpecException {
        String key = new String(Files.readAllBytes(Paths.get(filePath)))
            .replace("-----BEGIN PRIVATE KEY-----", "")
            .replace("-----END PRIVATE KEY-----", "")
            .replaceAll("\\s+", ""); // Remove all whitespace

        byte[] decodedKey = Base64.getDecoder().decode(key);
        PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(decodedKey);
        KeyFactory kf = KeyFactory.getInstance("RSA");
        return kf.generatePrivate(spec);
    }

    private static HttpRequest buildRequest(String targetUri, String filePath, PrivateKey privateKey) throws Exception {
        String method = "put";
        String path = "/n/" + namespace + "/b/" + bucketName + "/o/" + Paths.get(filePath).getFileName();
        String host = "objectstorage." + region + ".oraclecloud.com";
        String date = DateTimeFormatter.RFC_1123_DATE_TIME.format(ZonedDateTime.now(ZoneOffset.UTC));
        byte[] fileContent = Files.readAllBytes(Paths.get(filePath)); // Read file content as byte array

        String signingString = "(request-target): " + method.toLowerCase() + " " + path + "\n" +
                            "host: " + host + "\n" +
                            "date: " + date;
        System.out.println("Signing String: \n" + signingString);

        String signature = signRequest(privateKey, signingString);
        String authorizationHeader = "Signature version=\"1\",headers=\"(request-target) host date\",keyId=\"" +
            tenancyId + "/" + userId + "/" + keyFingerprint + "\",algorithm=\"rsa-sha256\",signature=\"" + signature + "\"";

        return HttpRequest.newBuilder()
                .uri(URI.create(targetUri))
                .header("Content-Type", "application/octet-stream")
                .header("date", date)
                .header("Authorization", authorizationHeader)
                .PUT(HttpRequest.BodyPublishers.ofByteArray(fileContent))
                .build();
    }

    private static String signRequest(PrivateKey privateKey, String dataToSign) throws Exception {
        Signature signatureInstance = Signature.getInstance("SHA256withRSA");
        signatureInstance.initSign(privateKey);
        signatureInstance.update(dataToSign.getBytes());
        byte[] signature = signatureInstance.sign();
        return Base64.getEncoder().encodeToString(signature);
    }
}

  3. Jetzt haben wir den gesamten Code in die JAVA-Datei eingefügt, lassen Sie uns daran arbeiten, die erforderlichen Werte zu aktualisieren und ihre Funktionalität zu verstehen.

    private static final String apiKeyFilePath = "C:\\Users\\User1\\Folder\\privatekey.pem"
private static final String tenancyId = "ocid1.tenancy.oc1..aaaaaaaackopa27emaz4uteg4q7"; // OCI Tenancy ID
private static final String userId = "ocid1.user.oc1..aaaaaaaafelqsoffcjq"; // OCI User ID
private static final String keyFingerprint = "72:d4:6c:f8:89:74:aa"; // OCI fingerprint
private static final String region = "us-ashburn-1"; // OCI Region
private static final String namespace = "ocitenancyname"; // OCI bucket namespace
private static final String bucketName = "ocibucketname"; // OCI bucket NAME

    Alle diese Werte sind für eine sichere Verbindung zu Ihrem OCI-Mandanten verantwortlich. Rufen Sie diese Werte aus der Konfigurationsdatei ab.

    String targetUri = "https://objectstorage." + region + ".oraclecloud.com/n/" + namespace + "/b/" + bucketName + "/o/" + fileName;
HttpRequest request = buildRequest(targetUri, filePath, privateKey);

    Dies ist der rest_api- und Hostendpunkt. Bereiten Sie ihn entsprechend Ihrer Anforderung vor, da sich dies für jeden Service ändert. Das hier gezeigte Beispiel ist der Endpunkt für OCI Object Storage Service für die Ashburn-Region.

    private static HttpRequest buildRequest

    Die Header für die REST-API wurden zusammen mit dem Inhaltstyp und anderen erforderlichen Parametern erstellt. Beachten Sie, dass hier Definitionen für method_type, Datum und Hostheader vorhanden sind, da für den Postanruf ein detailliertes Headerset erforderlich ist.

    private static String signRequest

    Schließlich erstellen wir die Signaturzeichenfolge und führen dann den REST-API-Aufruf durch. Beachten Sie, dass OCI die API-Aufrufe signieren muss. Deshalb tun wir dies hier.

  4. Nachdem Sie die Werte gemäß Ihrer Konfiguration aktualisiert haben, führen Sie den JAVA-Code aus. Daraufhin sollte das Skript angezeigt werden, dass alles gut ausgeführt wird, und die Datei wird an OCI Object Storage übertragen.

    Hinweis: Stellen Sie sicher, dass Java mit allen erforderlichen Packages installiert ist, wie es für den Code erforderlich ist.

Danksagungen

Weitere Lernressourcen

Lernen Sie andere Übungen auf docs.oracle.com/learn kennen, oder greifen Sie auf weitere kostenlose Lerninhalte im Oracle Learning YouTube Channel zu. Außerdem können Sie education.oracle.com/learning-explorer besuchen, um Oracle Learning Explorer zu werden.

Die Produktdokumentation finden Sie im Oracle Help Center.