Oracle Cloud Infrastructure Documentation

Advanced Concepts

This section covers PowerShell SDK concepts.

This section covers PowerShell SDK concepts.

Managing Session Preferences

The OCI Modules for PowerShell support the use of environment variables in a PowerShell session to specify values some optional common parameters. These environment variables can be configured directly in the PowerShell session or by using the Set-OCIClientSession cmdlet. Values assigned to these environment variables are used for making API calls only in the PowerShell session in which they are set.

Set Environment Variables Directly from PowerShell

The following environment variables can be used to specify values for some parameters used by the OCI Modules for PowerShell:
Cmdlet Parameter Environment Variable Name Note
Region OCI_PS_REGION If a value is not specfied, region value from the user preferred profile is used.
Profile OCI_PS_PROFILE If a value is not specified, the DEFAULT profile is used.
ConfigFile OCI_PS_CONFIG If a value is not specfied, config file at ~/.oci/config will be used.
NoRetry OCI_PS_NORETRY If a value is not specified, default retry strategy is used to attempt retries.
TimeOutInMillis OCI_PS_TIMEOUT If a value is not specified, the default value of 100,000 milliseconds (100 seconds) is used.
AuthType OCI_PS_AUTH If a value is not specified, the API key defined in the config file is used.

For example, to set the region: 

PS /> $Env:OCI_PS_REGION="us-phoenix-1"

Set Environment Variables using Cmdlets

You can use the Set-OCIClientSession and Get-OCIClientSession cmdlets to set and retrieve the session preference environment variables.

Set-OCIClientSession

This cmdlet sets the Region, Profile and Config file preferences for the PowerShell session through the environment variables shown above.

Note

Import OCI.PSModules.Common before running the following example.
PS /> Set-OCIClientSession -RegionId "us-ashburn-1" -Profile "Test" -Config "~/.oci/testconfig"
 
RegionId     Profile Config
--------     ------- ------
us-ashburn-1 Test    ~/.oci/testconfig

To remove a session preference environment variable, run the Clear-OCIClientSession cmdlet with the appropriate parameters.

Get-OCIClientSession

The Get-OCIClientSession cmdlet in the common module is used to retrieve the session preference values set for the common parameters from the current PowerShell session.

PS /> Get-OCIClientSession                                                                    
 
RegionId     Profile Config
--------     ------- ------
us-ashburn-1 Test

Parameter Precedence

When evaluating parameters, the OCI Modules for PowerShell follows this order of precedence:

  1. The value specified in the cmdlet parameter.
  2. The value specified in the session preferences.
  3. The value specified in the user-selected profile of the OCI configuration file located at ~/.oci/config.
Note

The OCI Modules for PowerShell use the DEFAULT profile as a fall back profile. Any value that isn't explicitly defined for a given profile is inherited from the DEFAULT profile.

History Store

By default, OCI Cmdlets output the response body of the underlying REST API operation. The history store provides users with a PowerShell variable that can be used to look into OCI Cmdlet invocations and their complete API responses from OCI services.
Note

Each PowerShell session gets its own history store.

You can use the history store to:

  • Use the previous Cmdlet's response object values in the next Cmdlet
  • Inspect the complete API response, including the response headers - for example, the use of e-tags for optimistic concurrency, or the OpcNextPage header for pagination
  • Examine cmdlet invocation sequences for diagnostic purposes

The history store is encapsulated as an Oci.PSModules.Common.Cmdlets.CmdletHistory.OCICmdletHistoryStore object in a PowerShell variable named $OCICmdletHistory.

For more information. see the History Store example on GitHub.

History Store Properties

This section explains the properties contained in the history store object stored in $OCICmdletHistory.

   TypeName: Oci.PSModules.Common.Cmdlets.CmdletHistory.OCICmdletHistoryStore
                
                Name         MemberType Definition
                ----         ---------- ----------
                Entries      Property   Oci.PSModules.Common.Cmdlets.CmdletHistory.OCICmdletHistory[] Entries {get;}
                LastResponse Property   psobject LastResponse {get;}
                Size         Property   int Size {get;}

Size

Indicates the maximum number of commands that can be saved in the history store. The default value is 20. Valid values are from 1 and 100000 (inclusive). To modify the size of history store, use Set-OCICmdletHistory.

Note

We recommend keeping the history size to a minimum to limit memory usage.

Entries

Collection of Oci.PSModules.Common.Cmdlets.CmdletHistory.OCICmdletHistory objects that allows indexed access to the stored history.

The Oci.PSModules.Common.Cmdlets.CmdletHistory.OCICmdletHistory object has the following properties:

Name Type Description
StartTime System.DateTime Start time of cmdlet execution.
EndTime System.DateTime End time of cmdlet execution.
Command System.Management.Automation.InvocationInfo Describes how and where this command was invoked.
Response System.Management.Automation.PSObject Output object returned by the cmdlet.

LastResponse

A System.Management.Automation.PSObject object encapsulating the last OCI Cmdlet response in a PowerShell session.

History Store Cmdlets

Oci.PSModules.Common module provides the following cmdlets for working with the History Store. See the GitHub example.

Get-OCICmdletHistory

Gets the cmdlet history stored in the current PowerShell session.

Set-OCICmdletHistory

Sets properties of the history store.

Clear-OCICmdletHistory

Deletes the cmdlet history stored in the current PowerShell session.

Pagination

OCI Cmdlets that invokes list API operations have the ability to paginate results, allowing you to retrieve the available results in batches (automatically following pagination tokens) until no more records are available.

Note

Examples in this topic call the ListImages operation in the Compute service. Be sure to import OCI.PSModules.Core before trying out the examples in this section.

Get First Page Results

The default behavior of a cmdlet that supports pagination is to get only the first page of results when invoked without the -Page parameter specified.

For example, to get the first page of compute images available invoke the Get-OCIComputeImagesList with your compartment ID:

PS /> Get-OCIComputeImagesList -CompartmentId $Env:CompartmentId | Measure-Object
 
Count             : 100

The above example implicitly sets the -Page parameter to NULL.

Note

The maximum number of results per page is defined by the service and can be found in the service API reference.

Limit Results

The -Limit parameter specifies the maximum number of results returned per page.

This example sets the maximum number of results returned per page to 5:

PS /> Get-OCIComputeImagesList -CompartmentId $Env:CompartmentId -Limit 5 | Measure-Object                                       
 
Count             : 5

Get Next Page Results

The -Page parameter is used to get the next page of results by passing the pagination token from the `opc-next-page` response header contained in the previous cmdlet response.

Note

You can use the history store to get the previous cmdlet response.

This example shows how to retrieve the results remaining from a previous paginated call by passing the $OCICmdletHistory.LastResponse.OpcNextPage property from the history store as the argument to the -Page parameter:.

PS /> Get-OCIComputeImagesList -CompartmentId $Env:CompartmentId -Page $OCICmdletHistory.LastResponse.OpcNextPage | Measure-Object
 
Count             : 100

Get All Results

OCI Cmdlets that support pagination can auto paginate and fetch results from all available pages. Let the cmdlet do the pagination by passing -All switch parameter when running the cmdlet.

PS /> Get-OCIComputeImagesList -CompartmentId $Env:CompartmentId -All | Measure-Object                                            
 
Count             : 293

Waiters and Asynchronous Calls

Most Oracle Cloud Infrastructure resources, such as compute instances, have lifecycles. In many cases, you want your command to wait until a resource or work request reaches a specific state, or a timeout is exceeded, before taking further action. You can poll a resource to determine its state.

OCI Modules for PowerShell offer waiter parameters that allow your cmdlet to wait until a resource reaches a desired state. A cmdlet with waiter parameters can be invoked in a blocking manner to wait until either one of the desired states is reached or a timeout is exceeded. Waiters abstract the polling logic that you would otherwise have to add before taking further actions on a resource or a workrequest.

For example, when you call LaunchInstance in the Compute service, the response header contains a work-request-id. The OCI Modules for PowerShell uses this ID when you specify the -WaitForStatus parameter, which causes your script to wait until the work request succeeds before proceeding.

For example:
#Create a new compute instance and wait for the instance work request to succeed or fail, 
#polling every 60 seconds and attempting 20 times max
$ComputeInstance = New-OCIComputeInstance -LaunchInstanceDetails $LaunchDetails -WaitForStatus Succeeded,Failed -MaxWaitAttempts 20 -WaitIntervalSeconds 60

Waiter parameters

This section describes the parameters used for asynchronous calls.

WaitForStatus

Specify this parameter to perform the action and then wait until the resource reaches the desired lifecycle state. Multiple states can be specified, returning when the resource reaches one of the desired states.

WaitIntervalSeconds

Check every WaitIntervalSeconds to see whether the resource has reached one of the desired states. Default value for this parameter is 30 seconds.

MaxWaitAttempts

Maximum number of attempts to be made until the resource reaches one of the desired states. Default value for this parameter is 3 attempts.

Note

Currently, OCI Cmdlets do not accept maximum wait time for cmdlets that support waiters. You can work around this limitation by controlling the values of MaxWaitAttempts and/or WaitIntervalSeconds.

On successful completion, the cmdlet returns the original response object received. In case of an error like the resource failing to reach the desired state within the given limits, an exception containing the error message would be thrown.

Stream Inputs and Outputs

Some OCI Cmdlets interact with APIs that accept or return stream type objects (for example, the InvokeFunctions operation in the Functions service). These OCI cmdlets accept parameters that can take a file path and implicitly convert files to streams and back.
Note

You can either pass a stream parameter or the equivalent file parameter, but not both.
The file input parameter is named after the corresponding stream input parameter and file output parameter is named as OutputFile.
Note

For an example, see the help text for the Invoke-OCIFunctionsInvokeFunction cmdlet in OCI.PSModules.Functions.

This sample on GitHub shows how to work with streams.

Logging

To facilitate troubleshooting, OCI Modules for PowerShell supports logging debug- and verbose-level messages on the console in addition to error messages. This feature has been integrated with the standard PowerShell Debug and Verbose parameters.

Pass the -Debug or -Verbose parameters in the cmdlet invocation to see log messages on the console.

For example:

PS /> Get-OCIComputeImagesList -CompartmentId $Env:CompartmentId -Limit 1 -Verbose
 
#More Verbose
PS /> Get-OCIComputeImagesList -CompartmentId $Env:CompartmentId -Limit 1 -Debug

Authenticating with Instance Principals

Instance principals is an IAM service feature that enables instances to be authorized actors (or principals) that can perform actions on service resources. Each compute instance has its own identity, and it authenticates using the certificates that are added to it. These certificates are automatically created, assigned to instances and rotated, preventing the need for you to distribute credentials to your hosts and rotate them.

Note

For more information on instance principals, see Calling Services from an Instance.

To enable instance principal authentication from OCI Cmdlets, call authorize the instance and set the AuthType parameter. For example:

PS /> Get-OCIIdentityRegionsList -AuthType InstancePrincipal

Dedicated Endpoints

Dedicated endpoints are the endpoint templates defined by the service for a specific realm at the client level. The OCI Modules for PowerShell allow you to enable the use of this realm-specific endpoint templates feature at both the application level and at the client level. This feature is disabled by default.
Note

The value set at client level takes precedence over the value set at the application level.

Enabling realm-specific endpoint templates at the application level:

To enable the realm-specific endpoint templates feature at the application level, set the environment variable OCI_REALM_SPECIFIC_SERVICE_ENDPOINT_TEMPLATE_ENABLED to true.
Note

The boolean value is case-insensitive.

Enabling realm-specific endpoint templates at the client level:

To enable the realm-specific endpoint templates feature at the client level, set the flag in code as shown below:
$NamespaceName = Get-OCIObjectStorageNamespace -CompartmentId $CompartmentId -UseRealmSpecificEndpoint -Debug

For a full example, see the CreateBucketUsingRealmSpecificEndpoint_ObjectStorage example on GitHub.