Working with Cmdlets

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

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.

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.