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.
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:
- The value specified in the cmdlet parameter.
- The value specified in the session preferences.
- The value specified in the user-selected profile of the OCI configuration file
located at
~/.oci/config
.
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
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
.
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.
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.
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.
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.
#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.
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
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. You can either pass a stream parameter or the equivalent file parameter, but not both.
OutputFile
. 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.
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
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:
OCI_REALM_SPECIFIC_SERVICE_ENDPOINT_TEMPLATE_ENABLED
to
true
. The boolean value is case-insensitive.
Enabling realm-specific endpoint templates at the client level:
$NamespaceName = Get-OCIObjectStorageNamespace -CompartmentId $CompartmentId -UseRealmSpecificEndpoint -Debug
For a full example, see the CreateBucketUsingRealmSpecificEndpoint_ObjectStorage example on GitHub.