Concepts

Les demandes brutes sont utiles et, dans certains cas, nécessaires. Cas d'utilisation courants : Lors de l'utilisation de votre propre client HTTP, qui soumet une demande OCI authentifiée à un autre point d'extrémité, et qui soumet une demande à une API OCI qui n'est pas prise en charge actuellement dans la trousse SDK. La trousse SDK pour TypeScript et JavaScript présente la classe DefaultRequestSigner que vous pouvez utiliser pour créer une instance et appeler signHttpRequest.

L'exemple de demande brute sur GitHub montre comment créer une instance de DefaultRequestSigner et appeler signHttpRequest.

Le service de stockage d'objets prend en charge les chargements en plusieurs parties pour faciliter les chargements d'objets volumineux en fractionnant l'objet volumineux en parties. La trousse SDK pour TypeScript et JavaScript prend en charge une classe de chargement de niveau supérieur utilisant les API de chargement en plusieurs parties. La rubrique Gestion des chargements en plusieurs parties fournit des liens aux API utilisées pour les opérations de chargement en plusieurs parties. Les chargements en plusieurs parties de niveau supérieur sont mis en oeuvre à l'aide d'UploadManager qui fractionne un objet volumineux en plusieurs parties pour vous, charge les parties en parallèle, puis recombine et valide les parties en un seul objet dans le stockage. L'exemple UploadObject montre comment utiliser UploadManager pour fractionner automatiquement un objet en plusieurs parties afin de simplifier les interactions avec le service de stockage d'objets.

Par défaut, la trousse SDK retente les opérations avec les codes de statut de réponse HTTP 409 (avec un code d'erreur IncorrectState), 429, 500, 502, 503, 504, les erreurs de temporisation (temporisations de connexion HTTP et de lecture, par exemple), les erreurs de connexion de demande, les exceptions de demande et les exceptions de disjoncteur.

Désactivation des nouvelles tentatives par défaut

Priorité du comportement des nouvelles tentatives

• Toute configuration définie explicitement au niveau de la demande remplace la configuration au niveau du client ou la configuration globale par défaut et la configuration au moyen de la variable d'environnement, pour cette demande spécifique.
• Toute configuration définie explicitement au niveau du client remplace la configuration globale par défaut et la configuration au moyen de la variable d'environnement, pour ce client particulier.
• La configuration par défaut définie au niveau global par programmation a priorité sur le remplacement au niveau de la variable d'environnement.

La trousse SDK pour TypeScript offre des processus en attente qui permettent à votre code d'attendre qu'une ressource spécifique atteigne l'état souhaité. Un processus en attente attend que l'état souhaité soit atteint ou qu'une temporisation soit dépassée. Les processus en attente convertissent la logique de scrutation (que vous auriez à écrire autrement) en un appel de méthode unique facile à utiliser.

Les processus en attente sont obtenus au moyen du client du service client.createWaiter(). Les processus en attente utilisent un objet de configuration facultatif pour permettre aux utilisateurs de contrôler la durée d'attente et la durée entre les tentatives de scrutation. L'exemple suivant montre comment créer un processus en attente avec la configuration facultative :

// The waiter configuration used when creating our waiters.
import common = require("oci-common");
import identity = require("oci-identity");

const maxTimeInSeconds = 60 * 60; // The duration for waiter configuration before failing. Currently set to 1 hour.
const maxDelayInSeconds = 30; // The max delay for the waiter configuration. Currently set to 30 seconds

const waiterConfiguration: common.WaiterConfiguration = {
  terminationStrategy: new common.MaxTimeTerminationStrategy(maxTimeInSeconds),
  delayStrategy: new common.ExponentialBackoffDelayStrategy(maxDelayInSeconds)
};

const identityClient = new identity.identityClient({ authenticationDetailsProvider: provider });
const identityWaiter = identityClient.createWaiters(waiterConfiguration);

À partir de la version 2.8.0, la trousse SDK pour Typescript et Javascript prend en charge les disjoncteurs par défaut. Les disjoncteurs permettent d'éviter que le client submerge le service en bloquant l'envoi des demandes à celui-ci après qu'un certain seuil d'échec a été atteint. Pour les disjoncteurs par défaut, toutes les erreurs pour lesquelles une nouvelle tentative est possible sont traitées comme des défaillances.

Les paramètres suivants définissent un disjoncteur :

• Seuil de taux d'échec - L'état du disjoncteur passe de CLOSED à OPEN lorsque le taux d'échec est égal ou supérieur à ce seuil. Par exemple, lorsque plus de 50 % des appels enregistrés ont échoué, le disjoncteur s'ouvre.
• Temporisation de réinitialisation - Délai après lequel un disjoncteur ouvert tente d'exécuter une demande.
• Exceptions d'échec - Liste des exceptions qui sont considérées comme des échecs pour le disjoncteur.
• Seuil de nombre minimal d'appels/volume - Nombre minimal d'appels requis (par période de fenêtre glissante) avant que le disjoncteur puisse calculer le taux d'erreur.

Configuration des coupe-circuits par défaut

La configuration des disjoncteurs par défaut est la suivante :

Désactivation du disjoncteur par défaut

Pour désactiver la fonction de disjoncteur par défaut, vous pouvez effectuer l'une des opérations suivantes :

Priorité du comportement du disjoncteur

Toute configuration définie explicitement au niveau du client remplace la configuration globale par défaut et le remplacement au niveau de l'environnement, pour ce client particulier.

Exemples de circuits

Pour des exemples TypeScript, voir Github.

Pour des exemples JavaScript, voir Github.

Les points d'extrémité de service peuvent être définis de trois façons :

• Définissez .endpoint = '<YOUR_ENDPOINT>' sur l'instance de service. Vous pouvez ainsi spécifier un nom d'hôte complet (par exemple, https://www.example.com).
• Réglez .region = '<YOUR_REGION_ID> sur l'instance de service. Cela sélectionne le nom d'hôte approprié pour le service dans la région indiquée. Toutefois, si le service n'est pas pris en charge dans la région que vous avez définie, la trousse SDK pour TypeScript et JavaScript retourne une erreur. Vous pouvez consulter la liste des ID région dans : ./oci-typescript-sdk/common/lib/region.ts
• Transmettez la région dans le fichier de configuration. Pour plus d'informations, voir Fichier de configuration des trousses SDK et de l'interface de ligne de commande.

Notez qu'une instance de service ne peut pas être utilisée pour communiquer avec différentes régions. Si vous devez faire des demandes à différentes régions, créez plusieurs instances de service.

Si vous utilisez une version de trousse SDK antérieure à l'annonce d'une nouvelle région, vous pouvez utiliser une solution de rechange pour l'atteindre.

Une région est une zone géographique localisée. Pour plus d'informations sur les régions et comment les identifier, voir Régions et domaines de disponibilité.

Un domaine est un jeu de régions qui partagent des entités. Vous pouvez identifier votre domaine en consultant son nom à la fin de l'adresse réseau. Par exemple, le domaine pour xyz.abc.123.oraclecloud.com est oraclecloud.com.

Vous devez d'abord appeler Region.register pour enregistrer la nouvelle région, puis vous pouvez définir la région en utilisant le fichier de configuration ou en définissant .region = <Your_new_registered_region>.

Pour les régions du domaine oraclecloud.com, vous pouvez transmettre de nouveaux noms de région, comme vous transmettriez des noms déjà définis dans l'énumération Région de votre version de trousse SDK.

Pour définir la région :

identityClient = await new identity.IdentityClient({ authenticationDetailsProvider: provider });
identityClient.region = 'us-phoenix-1'

Pour les régions des domaines autres que oraclecloud.com, vous pouvez utiliser les solutions suivantes pour atteindre de nouvelles régions avec des versions antérieures de la trousse SDK.

Pour définir le point d'extrémité :

// Instantiate an identity client
identityClient = await new identity.IdentityClient({ authenticationDetailsProvider: provider });
identityClient.endpoint = 'https://<your_endpoint>.com'

Il est parfois préférable de charger un résultat en différé. Pour extraire plus de données d'un chargement différé, vous devez continuer d'appeler l'opération de liste, en transmettant la valeur du jeton suivant de la réponse la plus récente. Grâce au module de pagination, vous pouvez :

• Charger facilement tous les résultats possibles à partir d'un appel de liste
• Charger les résultats en différé

Pour obtenir un exemple de l'utilisation de ces fonctions, consultez GitHub.

Lors du traitement d'une exception, vous pouvez obtenir plus d'informations sur la demande HTTP qui l'a générée, notamment le code de statut ou la temporisation. Vous pouvez également obtenir l'ID demande lors du traitement d'une exception en examinant la propriété opcRequestId de l'objet d'erreur.

try {
  const response = await identityClient.listAllUsersResponses(listUserReq);
} catch (err) {
  console.log('requestId: ', err.opcRequestId);
}

La trousse SDK pour TypeScript et JavaScript vous permet d'intégrer votre propre enregistreur automatique. La connexion à la trousse SDK se fait au moyen de l'interface de l'enregistreur automatique. Cette interface est une abstraction de journalisation qui permet l'utilisation d'une bibliothèque de journalisation fournie par l'utilisateur, comme log4js, bunyan ou winston.

Pour plus d'informations, voir l'exemple de journalisation sur GitHub.

// TypeScript
// Download the logger that you want to use with the SDK (like bunyan)
import { LOG } from "oci-sdk";
 var bunyan = require("bunyan");
  
 // Set the logger here
var bunLog = bunyan.createLogger({ name: "LoggingExample", level: "debug" });
 LOG.logger = bunLog;

// Javascript
import { LOG } from "oci-sdk";
 var bunyan = require("bunyan");
  
 // Set the logger here.
 var bunLog = bunyan.createLogger({ name: "LoggingExample", level: "debug" });
 LOG.logger = bunLog;