Remarques :

Gérer les API REST Oracle Cloud Infrastructure par programmation à l'aide de Shell et de Java Code

Introduction

Oracle Cloud Infrastructure (OCI) fournit une infrastructure cloud aux clients pour héberger leurs applications stratégiques sur le cloud. OCI fournit également au client les moyens d'accéder aux services OCI via la console ou via des API. Pour la connexion via des API, le client peut utiliser des kits SDK basés sur le langage de programmation de son choix, comme Java, Python ou Ruby. Mais il s'agit de quelques cas où les clients ne peuvent pas utiliser le SDK et ne peuvent pas utiliser de langage de programmation, mais souhaitent plutôt se connecter via des API directement à partir d'un outil, d'une base de données ou d'une application tierce où ils ne peuvent pas installer le SDK. L'utilisation des API REST est utile. Les clients peuvent tirer parti des API REST fournies par OCI pour presque tous les services et les utiliser directement dans leurs outils en mettant simplement à jour les adresses et en prenant en charge l'autorisation et l'authentification.

De nos jours, toutes les entreprises veulent tirer parti de la puissance des API REST dans leurs applications et créer une offre innovante pour leurs clients sans avoir à installer et gérer de SDK.

Dans ce tutoriel, nous allons discuter et comprendre comment OCI peut aider les entreprises du monde entier à tirer parti de la puissance des API REST avec OCI. Dans ce tutoriel, nous allons montrer des exemples d'API REST basées sur les scripts shell et le code Java.

Objectifs

Prérequis

Tâche 1 : configuration des clés d'API Oracle Cloud Infrastructure

  1. Connectez-vous à la location OCI avec le compte de service ou l'administrateur et accédez aux paramètres utilisateur.

    Ouvrir les paramètres utilisateur

    Ou

    Accédez à l'utilisateur à partir de la console OCI IAM. Assurez-vous que l'utilisateur dispose de tous les accès requis pour la création et la mise à jour de l'infrastructure sur OCI.

  2. Accédez à la section Ressources, cliquez sur Clés d'API et sur Ajouter une clé d'API. Sélectionnez cette option pour télécharger les nouvelles clés publiques et privées, télécharger votre clé publique ou coller votre clé publique.

    Ajouter une clé d'API

  3. Enregistrez les clés à un emplacement approprié et enregistrez le fichier de configuration comme indiqué dans la page suivante. Vous aurez besoin de ce fichier de configuration et de cette clé privée lors de la connexion à votre location à l'aide d'API REST.

    Enregistrer le fichier de configuration

    Remarque :

    • Vous aurez besoin de la même valeur configuration parameters pour vous connecter à la location et à la région OCI. Vous allez remplacer les paramètres dans le code Java et les scripts shell en conséquence au fur et à mesure que nous approfondissons le tutoriel.

    • Pour appeler des services OCI à partir d'instances OCI Compute, OCI offre un moyen plus sécurisé d'utiliser des principaux d'instance. Evitez d'utiliser des clés d'API utilisateur comme meilleures pratiques. Pour plus d'informations, reportez-vous à appel de services à partir d'une instance.

Tâche 2 : création et exécution d'un script shell pour télécharger ou placer un fichier binaire à partir d'OCI Object Storage à l'aide d'API REST

  1. Accédez au système de fichiers et créez un fichier shell. Pour cet exemple, le fichier est nommé PUT_OBJECT_REST_API.sh.

  2. Ouvrez le fichier avec l'éditeur de votre choix et collez le code suivant dans le fichier shell.

    • 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. Maintenant que tout le code est collé dans le fichier shell, travaillons à la mise à jour des valeurs requises et comprenons leur fonctionnalité.

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

    Toutes ces valeurs sont chargées d'établir une connexion sécurisée avec votre location OCI. Obtenez ces valeurs à partir du fichier de configuration.

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

    Il s'agit de l'adresse rest_api et host, préparez-la en fonction de vos besoins car cela changera pour chaque service. L'exemple présenté ici est l'adresse d'OCI Object Storage Service pour la région ashburn.

    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"

    Ici, nous avons créé les en-têtes pour l'API REST avec le type de contenu et d'autres paramètres requis. Notez que nous avons ici des définitions pour method_type, date et host headers, comme pour le post-appel, nous avons besoin d'un ensemble d'en-têtes détaillé.

    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" ...

    Enfin, nous créons la chaîne de signature, puis nous appelons l'API REST à l'aide de curl. Notez qu'OCI a besoin que les appels d'API soient signés, et c'est pourquoi nous le faisons ici.

  4. Une fois que vous avez mis à jour les valeurs conformément à votre configuration, exécutez le script shell, vous devez voir le script s'exécuter correctement et le fichier est propagé vers OCI Object Storage.

    Remarque :

    • Assurez-vous d'avoir mis à jour l'autorisation du fichier shell sur exécutable en la remplaçant par 755 ou gérez-la vous-même.

    • Vous pouvez également le faire sous Windows en utilisant powerhell, ou utiliser le même script sous Windows en installant un WSL (sous-système Windows pour Linux) comme Ubuntu et l'exécuter à partir d'Ubuntu WSL sous Windows. Pour plus d'informations, reportez-vous à la section Windows Subsystem for Linux.

Tâche 3 : créer et exécuter du code Java pour télécharger ou placer un fichier binaire à partir d'OCI Object Storage à l'aide d'API REST

  1. Accédez au système de fichiers et créez un fichier java. Pour cet exemple, le fichier est nommé PUT_OBJECT_REST_API.java.

  2. Ouvrez le fichier avec l'éditeur de votre choix et collez le code suivant dans le fichier shell.

    • 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. Maintenant que tout le code est collé dans le fichier java, travaillons à la mise à jour des valeurs requises et comprenons leur fonctionnalité.

    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

    Toutes ces valeurs sont chargées d'établir une connexion sécurisée avec votre location OCI. Obtenez ces valeurs à partir du fichier de configuration.

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

    Il s'agit de l'adresse rest_api et de l'adresse hôte. Préparez-la conformément à vos besoins, car cela changera pour chaque service. L'exemple présenté ici est l'adresse d'OCI Object Storage Service pour la région ashburn.

    private static HttpRequest buildRequest

    Nous avons créé les en-têtes pour l'API REST avec le type de contenu et d'autres paramètres requis. Notez qu'ici, nous avons des définitions pour method_type, date et en-têtes d'hôte, car pour le post-appel, nous avons besoin d'un ensemble d'en-têtes détaillé.

    private static String signRequest

    Enfin, nous créons la chaîne de signature, puis nous appelons l'API REST. Notez qu'OCI a besoin que les appels d'API soient signés, et c'est pourquoi nous le faisons ici.

  4. Une fois que vous avez mis à jour les valeurs conformément à votre configuration, exécutez le code java, vous devez voir le script s'exécuter correctement et le fichier est propagé vers OCI Object Storage.

    Remarque : assurez-vous que Java est installé avec tous les packages requis, selon les besoins du code.

Remerciements

Ressources de formation supplémentaires

Parcourez d'autres ateliers sur docs.oracle.com/learn ou accédez à davantage de contenus de formation gratuits sur le canal Oracle Learning YouTube. De plus, rendez-vous sur education.oracle.com/learning-explorer pour devenir un explorateur Oracle Learning.

Pour obtenir de la documentation sur le produit, visitez Oracle Help Center.