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.
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
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.
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.
For more detailed help information, use the
-Full
parameter.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.
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.