Working with Cmdlets

This section describes how to use the OCI Modules for PowerShell cmdlets.

The OCI Modules for PowerShell cmdlets are built on the Oracle Cloud Infrastructure SDK for .NET. These cmdlets make calls to Oracle Cloud Infrastructure REST APIs with the passed cmdlet parameter values.

Note

Cmdlet parameters are named corresponding to the respective REST API parameters as listed in the API reference.

The OCI REST APIs use HTTPS requests and responses. For more information, see About the API.

Cmdlet Discovery

OCI Cmdlets are named using a verb -noun pair pattern, where verb is the operation performed on the resource denoted by the noun, which usually includes the service name followed by the name of the resource in that service.

For example, the following command returns all cmdlets available to work with a compute instance resource in the Compute service, which is part of the OCI Core PowerShell module:

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
Note

The standard Get-Command can be used to find cmdlets present in any module.

Sample Cmdlet

This example shows how to invoke a simple OCI cmdlet that calls the GetNamespace operation of the OCI Object Storage service. This operation returns the name of the Object Storage namespace for the user making the request.

Note

Install and import the ObjectStorage service before trying out this example. For more information, see Installation.
PS /> Get-OCIObjectStorageNamespace
  
us-phx-test-namespace

Cmdlet Help

To get help information for a cmdlet, use the Get-Help cmdlet, passing in the name of the cmdlet as a parameter.

Note

For more detailed help information, use the -Full parameter.
This example shows help output for the Get-OCIObjectStorageNamespace cmdlet:
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

Common Parameters

This section describes the optional global cmdlet parameters common to all cmdlets present in any OCI PowerShell service module.

ConfigFile

The path to the configuration file that supplies credentials for the Oracle Cloud.

Endpoint

Indicates the service endpoint to use for OCI API calls, including any required API version path. For example, https://audit.us-ashburn-1.oraclecloud.com

FullResponse

By default, OCI Cmdlets output the response body of the REST API operation. Including the FullResponse switch parameter indicates that the cmdlet should output the complete response returned by the API operation wrapped in its associated .NET type (an object containing API response headers in-addition to an optional response body).

NoRetry

A switch parameter to disable default retry logic for calls to services.

By default, OCI Modules for PowerShell retry failed API calls that return status codes 400, 401, 404, 409, 429 and 500. Retry attempts use an exponential backoff algorithm with a maximum of 5 attempts over a maximum time span of 10 minutes. Include this switch parameter in the cmdlet invocation to disable the default retry logic.

Profile

Specifies which profile to load from the configuration file. This parameter expects a case-sensitive profile name existing in the configuration file.

Region

Specifies the Region-ID of the region to make calls against. For example: us-phoenix-1 or ap-singapore-1.

TimeOutInMillis

Specifies the maximum wait time in milliseconds for the API request to complete. The default value is 100,000 milli-seconds (100 seconds).

AuthType

Defines the type of authentication to use for making API requests. By default the API Key in your config file is used. Valid values are ApiKey or InstancePrincipal.

Cmdlet Input and Output

This section describes how the OCI Cmdlets process input and output.

Cmdlet Input

OCI Cmdlets currently accept inputs from command line parameters or through pipeline by property names. To see an example on passing inputs through pipeline by property name refer this sample.

Cmdlet Output

By default, OCI Cmdlets return only the API response body encapsulated in an associated .NET type. For use cases that require the users to inspect the complete API response including the response headers, use the FullResponse switch parameter in the cmdlet invocation.

In the following example, the GetConfiguration operation in the OCI Audit service returns a Configuration resource in the response body.

Note

To run the following example, import 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;}

In the example output above, the default invocation only returns the .NET object that encapsulates the API response body.

To get an output object that includes the complete API response include the -FullResponse parameter in the cmdlet invocation. For example:

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;}

Asynchronous Calls

For Oracle Cloud APIs that return an asynchronous work request response, with opc-work-request-id in the response header and no response body, OCI PowerShell Cmdlets return a Oci.PSModules.Common.Cmdlets.WorkRequest object containing the OpcWorkRequestId property.

For example:


   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;}

Error Handling

If an error occurs when running an OCI Cmdlet, the cmdlet throws a terminating error with an error record containing the exception and an error message about the underlying cause.