概念

Rawリクエストは役に立ちます。場合によっては必要です。一般的なユースケースは、独自のHTTPクライアントを使用して、代替エンドポイントへのOCI認証リクエストを作成する場合、およびSDKで現在サポートされていないOCI APIに対してリクエストを作成する場合です。SDK for TypeScript and JavaScriptは、インスタンスの作成およびsignHttpRequestのコールに使用できるDefaultRequestSignerクラスを公開します。

GitHubのRAWリクエストの例では、DefaultRequestSignerのインスタンスを作成し、signHttpRequestをコールする方法が示されています。

オブジェクト・ストレージ・サービスではマルチパート・アップロードがサポートされています。ラージ・オブジェクトをパートに分割することでラージ・オブジェクトのアップロードが容易になります。SDK for TypeScriptおよびSDK for JavaScriptでは、マルチパート・アップロードAPIを使用する上位レベルのアップロード・クラスがサポートされています。マルチパート・アップロードの管理では、マルチパート・アップロード操作で使用されるAPIへのリンクが示されています。高レベルのマルチパート・アップロードは、UploadManagerを使用して実装されます。これは、ラージ・オブジェクトをパートに分割し、パートを並列でアップロードした後で、パートを再結合してストレージでコミットします。UploadObjectの例では、オブジェクト・ストレージ・サービスとの相互作用を簡略化するため、UploadManagerを使用して、アップロード用にオブジェクトを自動的にパート分割する方法を示します。

SDKでデフォルトで再試行されるのは、HTTPレスポンス・ステータス・コードが409 (IncorrectStateエラー・コードあり)、429、500、502、503、504の操作、タイムアウト・エラー(HTTP接続および読取りタイムアウトなど)、リクエスト接続エラー、リクエスト例外およびサーキット・ブレーカ例外です。

デフォルトの再試行の無効化

再試行動作の優先順位

• リクエスト・レベルで明示的に定義した再試行構成では、クライアント・レベルの再試行構成またはグローバル・レベルのデフォルトの再試行構成と、その特定のリクエストの環境変数オーバーライドがオーバーライドされます。
• クライアント・レベルで明示的に定義された再試行構成では、グローバルのデフォルトの再試行構成、およびその特定のクライアントの環境変数レベルのオーバーライドがオーバーライドされます。
• グローバル・レベルで設定されたデフォルトの再試行構成では、環境変数レベルのオーバーライドがプログラムでオーバーライドされます。

OCI SDK for TypeScriptに用意されているウェイタを使用すると、特定のリソースが適切な状態になるまでコードを待機できます。ウェイタは、適切な状態になるかタイムアウトを超過するまで待機します。ウェイタによってポーリング・ロジックが抽象化されます。これがなければ、ユーザーが、使いやすい1つのメソッド・コールとしてロジックを記述する必要があります。

ウェイタは、サービス・クライアントclient.createWaiter()を介して取得されます。ウェイタは、オプションの構成オブジェクトを取得し、ユーザーが待機期間とポーリング試行間の時間を制御できるようにします。次の例では、オプションの構成を使用してウェイタを作成する方法を示しています:

// 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);

バージョン2.8.0以降、TypescriptおよびJavascriptのSDKでは、回路遮断器のデフォルト・サポートが提供されます。サーキット・ブレーカを使用すると、特定の失敗のしきい値に達した後、サービスにリクエストが送信されないようにすることで、クライアントがサービスに負荷をかけるのを防ぐことができます。デフォルトのサーキット・ブレーカでは、再試行可能なすべてのエラーは、そのサーキット・ブレーカの失敗として処理されます。

次のパラメータで、サーキット・ブレーカを定義します:

• 失敗率のしきい値 - 失敗率がこのしきい値以上になると、サーキット・ブレーカの状態がクローズからオープンに変わります。たとえば、記録されたコールの失敗が50%を超えると、サーキット・ブレーカがオープンになります。
• タイムアウトのリセット - リクエストが行われた場合、このタイムアウトが経過してから、オープン状態のサーキット・ブレーカでリクエストが試行されます
• 失敗の例外 - そのサーキットの失敗とみなされる例外のリスト
• 最小コール数/ボリュームのしきい値 - サーキット・ブレーカがエラー率を計算するために必要な最小コール数(スライディング・ウィンドウ期間ごと)

デフォルトのサーキット・ブレーカ構成

デフォルトのサーキット・ブレーカ構成は次のとおりです:

デフォルトのサーキット・ブレーカの無効化

デフォルトのサーキット・ブレーカ機能をオプトアウトするには、次のいずれかを実行します:

サーキット・ブレーカの動作の優先順位

クライアント・レベルで明示的に定義したサーキット・ブレーカ構成は、グローバルのデフォルトのサーキット・ブレーカ構成、およびその特定クライアントの環境レベルのオーバーライドをオーバーライドします。

回路遮断器の例

TypeScriptの例は、Githubを参照してください。

JavaScriptの例は、Githubを参照してください。

サービス・エンドポイントは3つの方法で設定できます:

• サービス・インスタンスで.endpoint = '<YOUR_ENDPOINT>'を設定します。こうすると、完全なホスト名(たとえばhttps://www.example.com)を指定できます。
• サービス・インスタンスで.region = '<YOUR_REGION_ID>を設定します。こうすると、指定したリージョンのサービスに適切なホスト名が選択されます。ただし、設定したリージョンでサービスがサポートされていない場合は、SDK for TypeScript and JavaScriptからエラーが返されます。regionIdのリストは、./oci-typescript-sdk/common/lib/region.tsで参照できます
• 構成ファイルでリージョンを渡します。詳細は、SDKおよびCLIの構成ファイルを参照してください。

サービス・インスタンスは、様々なリージョンとの通信には使用できないことに注意してください。様々なリージョンへのリクエストを行う必要がある場合は、複数のサービス・インスタンスを作成します。

新リージョン発表の前にリリースされたSDKのバージョンを使用している場合は、そのリージョンにアクセスするための対処方法を使用できます。

リージョンとは、限定された地理的領域のことです。リージョンの詳細と指定方法は、リージョンおよび可用性ドメインを参照してください。

レルムは、エンティティを共有する一連のリージョンです。ネットワーク・アドレスの最後にあるドメイン名を見ると、レルムがわかります。たとえば、xyz.abc.123.oraclecloud.comのレルムは、oraclecloud.comです。

最初にRegion.registerをコールして新しいリージョンを登録する必要があります。その後、構成ファイルを使用するか、set .region = <Your_new_registered_region>によって、リージョンを設定できます。

oraclecloud.comレルムのリージョンの場合、SDKバージョンのリージョン列挙にすでに定義されているリージョン名を渡すのと同じように、新しいリージョン名を渡すことができます。

リージョンを設定するには:

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

oraclecloud.com以外のレルムのリージョンの場合は、次の対処方法を使用して、以前のバージョンのSDKで新しいリージョンにアクセスできます。

エンドポイントを設定するには:

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

場合によっては、結果を遅延ロードする方が適しています。遅延ロードのデータをさらに取得するには、最新のレスポンスの次のトークンの値を渡して、リスト操作のコールを続ける必要があります。ページ区切りモジュールを使用すると、次が可能です:

• リスト・コールに含まれるすべての結果を先行してロード
• 結果を遅延ロード

これらのファンクションの使用例については、GitHubを参照してください。

例外を処理するとき、原因となったHTTPリクエストに関する詳細(ステータス・コードやタイムアウトなど)を取得できます。例外を処理するときに、エラー・オブジェクトのopcRequestIdプロパティを参照してリクエストIDを取得することもできます。

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

SDK for Typescript and JavaScriptでは、独自のロガーを統合できます。SDKでのロギングは、Loggerインタフェースを介して行われます。このインタフェースは、log4js、bunyan、winstonなどのユーザー指定のロギング・ライブラリを使用できるようにするロギング抽象化機能です。

詳細は、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;