コマンドレットの作業

この項では、OCI Modules for PowerShellコマンドレットの使用方法について説明します。

OCI Modules for PowerShellコマンドレットは、Oracle Cloud Infrastructure SDK for .NET上に構築されています。これらのコマンドレットは、渡されたコマンドレット・パラメータ値を使用してOracle Cloud Infrastructure REST APIをコールします。

ノート

コマンドレットのパラメータ名は、APIリファレンスにリストされているREST APIパラメータそれぞれに対応しています。

OCI REST APIでは、HTTPSリクエストおよびレスポンスが使用されます。詳細は、APIについてを参照してください

コマンドレットの検出

OCIコマンドレットの名前では動詞- 名詞というペアのパターンが使用されます(動詞は、名詞で示されるリソースに対して実行される操作です(通常、名詞では、サービス名のあとにそのサービス内のリソースの名前が続きます)。

たとえば、次のコマンドを実行すると、OCI Core PowerShellモジュールに含まれる、コンピュート・サービスのコンピューティング・インスタンス・リソースの操作に使用できるすべてのコマンドラインレットが返されます:

PS /> Get-Command -Module OCI.PSModules.Core -Noun "*ComputeInstance*"
 
CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Cmdlet          Get-OCIComputeInstance                             0.1.0      OCI.PSModules.Core
Cmdlet          Get-OCIComputeInstanceConsoleConnection            0.1.0      OCI.PSModules.Core
Cmdlet          Get-OCIComputeInstanceConsoleConnectionsList       0.1.0      OCI.PSModules.Core
Cmdlet          Get-OCIComputeInstanceDevicesList                  0.1.0      OCI.PSModules.Core
Cmdlet          Get-OCIComputeInstancesList                        0.1.0      OCI.PSModules.Core
Cmdlet          Invoke-OCIComputeInstanceAction                    0.1.0      OCI.PSModules.Core
Cmdlet          Move-OCIComputeInstanceCompartment                 0.1.0      OCI.PSModules.Core
Cmdlet          New-OCIComputeInstance                             0.1.0      OCI.PSModules.Core
Cmdlet          New-OCIComputeInstanceConsoleConnection            0.1.0      OCI.PSModules.Core
Cmdlet          Remove-OCIComputeInstanceConsoleConnection         0.1.0      OCI.PSModules.Core
Cmdlet          Update-OCIComputeInstance                          0.1.0      OCI.PSModules.Core

ノート

標準のGet-Commandを使用すると、すべてのモジュールに存在するコマンドレットを検索できます。

サンプル・コマンドレット

この例は、OCI Object StorageサービスのGetNamespace操作をコールする単純なOCIコマンドレットを起動する方法を示します。この操作は、リクエストを行ったユーザーのオブジェクト・ストレージ・ネームスペースの名前を返します。

ノート

この例を試す前に、ObjectStorageサービスをインストールおよびインポートします。詳細は、インストールを参照してください。

PS /> Get-OCIObjectStorageNamespace
  
us-phx-test-namespace

コマンドレットのヘルプ

コマンドレットのヘルプ情報を取得するには、Get-Helpコマンドレットを使用して、コマンドレットの名前をパラメータとして渡します。

ノート

詳しいヘルプ情報を取得するには-Fullパラメータを使用してください。

この例は、Get-OCIObjectStorageNamespaceコマンドレットのヘルプ出力を示します:

PS /> Get-Help Get-OCIObjectStorageNamespace
 
NAME
    Get-OCIObjectStorageNamespace
     
SYNOPSIS
    Invokes ObjectStorage service - GetNamespace operation.
     
     
SYNTAX
    Get-OCIObjectStorageNamespace [-OpcClientRequestId <String>] [-CompartmentId <String>] [-ConfigFile <String>] [-Endpoint <String>] [-NoRetry
    <SwitchParameter>] [-Profile <String>] [-Region <String>] [-FullResponse <SwitchParameter>] [-TimeOutInMillis <Int32>] [<CommonParameters>]
     
     
DESCRIPTION
    Each Oracle Cloud Infrastructure tenant is assigned one unique and uneditable Object Storage namespace. The namespace   is a system-generated string
    assigned during account creation. For some older tenancies, the namespace string may be   the tenancy name in all lower-case letters. You cannot edit a
    namespace.   GetNamespace returns the name of the Object Storage namespace for the user making the request.   If an optional compartmentId query parameter
    is provided, GetNamespace returns the namespace name of the corresponding   tenancy, provided the user has access to it.
     
 
RELATED LINKS
    APIReference https://docs.cloud.oracle.com/en-us/iaas/api/
 
REMARKS
    To see the examples, type: "Get-Help Get-OCIObjectStorageNamespace -Examples"
    For more information, type: "Get-Help Get-OCIObjectStorageNamespace -Detailed"
    For technical information, type: "Get-Help Get-OCIObjectStorageNamespace -Full"
    For online help, type: "Get-Help Get-OCIObjectStorageNamespace -Online

共通パラメータ

この項では、すべてのOCI PowerShellサービス・モジュールに存在するすべてのコマンドレットに共通する、オプションのグローバル・コマンドレット・パラメータについて説明します。

ConfigFile

Oracle Cloudの資格証明を提供する構成ファイルへのパス。

Endpoint

OCI APIコールに使用するサービス・エンドポイントを、必要なAPIバージョン・パスを含めて指定します。たとえば、https://audit.us-ashburn-1.oraclecloud.com

FullResponse

デフォルトでは、OCIコマンドレットはREST API操作のレスポンス本文を出力します。FullResponseスイッチ・パラメータを含めると、関連付けられた.NETタイプでラップされた、API操作で返される完全なレスポンス(オプションのレスポンス本文に加えてAPIレスポンス・ヘッダーを含むオブジェクト)を出力する必要があることをコマンドレットに指示します。

NoRetry

サービスに対するコールのデフォルトの再試行ロジックを無効にするスイッチ・パラメータ。

デフォルトでは、OCI Modules for PowerShellは、失敗したAPIコール(ステータス・コード400、401、404、409、429および500を返す)を再試行します。再試行では、最長10分間で最大試行回数5回の指数関数的バックオフ・アルゴリズムが使用されます。コマンドレットの呼出しにこのスイッチ・パラメータを含めると、デフォルトの再試行ロジックが無効になります。

Profile

構成ファイルからロードするプロファイルを指定します。このパラメータでは、構成ファイルに大/小文字が区別されるプロファイル名が存在する必要があります。

Region

コールを行うリージョンのRegion-IDを指定します。例: us-phoenix-1またはap-singapore-1。

TimeOutInMillis

APIリクエストの完了までの最大待機時間をミリ秒単位で指定します。デフォルト値は100,000ミリ秒(100秒)です。

AuthType

APIリクエストの作成に使用する認証のタイプを定義します。デフォルトでは、構成ファイルのAPIキーが使用されます。有効な値は、ApiKeyまたはInstancePrincipalです。

コマンドレットの入力および出力

この項では、OCIコマンドレットが入力および出力をどのように処理するかについて説明します。

コマンドレットの入力

現在、OCIコマンドレットは、コマンドライン・パラメータからの入力、またはプロパティ名によるパイプラインを介した入力を受け入れます。プロパティ名によりパイプラインを介して入力を渡す例は、このサンプルを参照してください。

コマンドレットの出力

デフォルトでは、OCIコマンドレットは、関連付けられた.NETタイプにカプセル化されたAPIレスポンス本文のみを返します。レスポンス・ヘッダーを含む完全なAPIレスポンスをユーザーが調べる必要があるユースケースでは、コマンドレットの呼出しでFullResponseスイッチ・パラメータを使用します。

次の例では、OCI AuditサービスのGetConfiguration操作が、レスポンス本文でConfigurationリソースを返しています。

ノート

次の例を実行するには、OCI.PSModules.Auditをインポートします。

PS /> Get-OCIAuditConfiguration -CompartmentId $env:CompartmentId | gm
 
   TypeName: Oci.AuditService.Models.Configuration
 
Name                MemberType Definition
----                ---------- ----------
Equals              Method     bool Equals(System.Object obj)
GetHashCode         Method     int GetHashCode()
GetType             Method     type GetType()
ToString            Method     string ToString()
RetentionPeriodDays Property   System.Nullable[int] RetentionPeriodDays {get;set;}

前述の出力例で、デフォルトの呼出しによって、APIレスポンス本文をカプセル化する.NETオブジェクトのみが返されます。

完全なAPIレスポンスを含む出力オブジェクトを取得するには、コマンドレットの呼出しに-FullResponseパラメータを含めます。例:

PS /> Get-OCIAuditConfiguration -CompartmentId $env:CompartmentId -FullResponse | gm                                                              
 
   TypeName: Oci.AuditService.Responses.GetConfigurationResponse
 
Name          MemberType Definition
----          ---------- ----------
Equals        Method     bool Equals(System.Object obj)
GetHashCode   Method     int GetHashCode()
GetType       Method     type GetType()
ToString      Method     string ToString()
Configuration Property   Oci.AuditService.Models.Configuration Configuration {get;set;}

非同期コール

非同期作業リクエスト・レスポンスを返し(レスポンス・ヘッダーにopc-work-request-idがあり、レスポンス本文がない)を返すOracle Cloud APIの場合、OCI PowerShellコマンドレットはOpcWorkRequestIdプロパティを含むOci.PSModules.Common.Cmdlets.WorkRequestオブジェクトを戻します。

例:


   TypeName: Oci.PSModules.Common.Cmdlets.WorkRequest
 
Name             MemberType Definition
----             ---------- ----------
Equals           Method     bool Equals(System.Object obj)
GetHashCode      Method     int GetHashCode()
GetType          Method     type GetType()
ToString         Method     string ToString()
OpcWorkRequestId Property   string OpcWorkRequestId {get;set;}

エラー処理

OCIコマンドレットの実行中にエラーが発生すると、コマンドレットは、例外を含むエラー・レコードと根本的な原因に関するエラー・メッセージとともに、終了エラーをスローします。

Oracle Cloud Infrastructureドキュメント