Note :

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

Présentation

Oracle Cloud Infrastructure(OCI) fournit une infrastructure en nuage aux clients pour héberger leurs applications essentielles sur le nuage. OCI fournit également au client des moyens d'accéder aux services OCI au moyen de la console ou d'API. Pour la connexion au moyen d'API, le client peut utiliser des trousses SDK basées sur le langage de programmation de son choix, par exemple Java, Python ou Ruby. Mais ce sont quelques cas où le client ne peut pas utiliser la trousse SDK et ne peut utiliser aucun langage de programmation, mais souhaite plutôt se connecter au moyen d'API directement à partir d'un outil, d'une base de données ou d'une application tierce où il ne peut pas installer la trousse SDK. Voici l'utilisation des API REST qui s'avère pratique. 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 à jour les points d'extrémité et en prenant soin de l'autorisation et de l'authentification.

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

Dans ce tutoriel, nous allons discuter et comprendre comment OCI peut aider les organisations du monde entier à tirer parti de la puissance des API REST avec OCI. Dans ce tutoriel, nous présenterons un exemple d'API REST basées sur des scripts d'interpréteur de commandes et du code Java.

Objectifs

Préalables

Tâche 1 : Configurer les clés d'API Oracle Cloud Infrastructure

  1. Connectez-vous à la location OCI avec le compte de service ou l'utilisateur administrateur et allez à Paramètres de l'utilisateur.

    Ouvrir les paramètres de l'utilisateur

    Ou

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

  2. Allez à 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, charger votre clé publique ou coller votre clé publique.

    Ajouter une clé d'API

  3. Enregistrez les clés à un emplacement pratique 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

    Note :

    • Vous aurez besoin du même configuration parameters pour vous connecter à votre région et à votre location 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 de calcul OCI, OCI fournit un moyen plus sécurisé à l'aide des principaux d'instance. Évitez d'utiliser des clés d'API d'utilisateur comme meilleures pratiques. Pour plus d'informations, voir Appel de services à partir d'une instance.

Tâche 2 : Créer et exécuter un script d'interpréteur de commandes pour charger ou placer un fichier binaire à partir du stockage d'objets OCI à l'aide d'API REST

  1. Allez au système de fichiers et créez un fichier d'interpréteur de commandes. Dans cet exemple, le fichier 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, nous avons tout le code collé dans le fichier shell, travaillons sur la mise à jour des valeurs requises et comprenons leurs fonctionnalités.

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

    Toutes ces valeurs sont responsables 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 du point d'extrémité rest_api et de l'hôte. Préparez-le selon vos besoins, car il sera modifié pour chaque service. L'exemple présenté ici est un point d'extrémité pour le service de stockage d'objets OCI 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 de l'API REST, ainsi que le type de contenu et les autres paramètres requis. Notez qu'ici, nous avons des définitions pour method_type, date et en-têtes d'hôte comme pour l'appel postérieur, nous avons besoin d'un jeu 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. Après avoir mis à jour les valeurs en fonction de votre configuration, exécutez le script d'interpréteur de commandes, vous devriez voir le script s'exécuter correctement et le fichier est poussé vers le stockage d'objets OCI.

    Note :

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

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

Tâche 3 : Créer et exécuter du code Java pour charger ou placer un fichier binaire à partir du service de stockage d'objets pour OCI à l'aide d'API REST

  1. Allez dans le système de fichiers et créez un fichier java. Dans cet exemple, le fichier 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, nous avons tout le code collé dans le fichier java, travaillons sur la mise à jour des valeurs requises et comprenons leurs fonctionnalités.

    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 responsables 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 du point d'extrémité rest_api et de l'hôte, préparez-le selon vos besoins, car cela changera pour chaque service. L'exemple présenté ici est un point d'extrémité pour le service de stockage d'objets OCI pour la région ashburn.

    private static HttpRequest buildRequest

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

    private static String signRequest

    Enfin, nous créons la chaîne de signature, puis nous faisons l'appel de 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. Après avoir mis à jour les valeurs en fonction de votre configuration, exécutez le code java, vous devriez voir le script s'exécuter correctement et le fichier est poussé vers le stockage d'objets OCI.

    Note : Assurez-vous que Java est installé avec tous les ensembles requis, selon les besoins du code.

Confirmation

Autres ressources d'apprentissage

Explorez d'autres laboratoires sur la page docs.oracle.com/learn ou accédez à plus de contenu d'apprentissage gratuit sur le canal YouTube d'Oracle Learning. De plus, visitez education.oracle.com/learning-explorer pour devenir un explorateur Oracle Learning.

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