Trabalhando com Cmdlets

Esta seção descreve como usar os Módulos do OCI para cmdlets PowerShell.

Os cmdlets de Módulos do OCI para PowerShell são criados no Oracle Cloud Infrastructure SDK para .NET. Esses cmdlets fazem chamadas para APIs REST do Oracle Cloud Infrastructure com os valores de parâmetro cmdlet informados.

Observação

Os parâmetros cmdlet são nomeados correspondentes aos respectivos parâmetros da API REST, conforme listado na referência da API.

As APIs REST do OCI usam solicitações e respostas HTTPS. Para obter mais informações, consulte Sobre a API.

Descoberta de Cmdlet

Os Cmdlets da OCI são nomeados usando um padrão do par verbo -substantivo, no qual verbo é a operação executada no recurso denotado pelo substantivo, que geralmente inclui o nome de serviço seguido pelo nome dos recursos nesse serviço.

Por exemplo, o seguinte comando retorna todos os cmdlets disponíveis para trabalhar com um recurso de instância de computação no serviço de computação, que faz parte do módulo OCI Core PowerShell:

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

Observação

O Comando Get- padrão pode ser usado para localizar cmdlets presentes em qualquer módulo.

Cmdlet de Amostra

Este exemplo mostra como chamar um cmdlet simples do OCI que chama a operação GetNamespace do serviço OCI Object Storage. Esta operação retorna o nome do namespace do Object Storage para o usuário que está fazendo a solicitação.

Observação

Instale e importe o serviço ObjectStorage antes de testar esse exemplo. Para obter mais informações, consulte Instalação.

PS /> Get-OCIObjectStorageNamespace
  
us-phx-test-namespace

Ajuda do Cmdlet

Para obter informações de ajuda para um cmdlet, use o cmdlet Get-Help, informando o nome do cmdlet como parâmetro.

Observação

Para obter informações mais detalhadas de a ajuda, use o parâmetro -Full.

Este exemplo mostra a saída da ajuda para o cmdlet Get-OCIObjectStorageNamespace:

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

Parâmetros Comuns

Esta seção descreve os parâmetros de cmdlet globais opcionais comuns a todos os cmdlets presentes em qualquer módulo de serviço do OCI PowerShell.

ConfigFile

O caminho para o arquivo de configuração que fornece credenciais para o Oracle Cloud.

Ponto Final

Indica o ponto final do serviço a ser usado nas chamadas de API do OCI, incluindo qualquer caminho obrigatório de versão da API. Por exemplo, https://audit.us-ashburn-1.oraclecloud.com

FullResponse

Por default, os Cmdlets do OCI geram o corpo de resposta da operação da API REST. A inclusão do parâmetro de alternância FullResponse indica que o cmdlet deve gerar a resposta completa retornada pela operação da API encapsulada em seu tipo .NET associado (um objeto que contém cabeçalhos de resposta da API além de um corpo de resposta opcional).

NoRetry

Um parâmetro de alternância para desativar a lógica de repetição padrão para chamadas de serviços.

Por padrão, os Módulos do OCI para PowerShell repetem as chamadas de API com falha que retornam códigos de status 400, 401, 404, 409, 429 e 500. As tentativas de repetição usam um algoritmo de backoff exponencial com no máximo 5 tentativas durante um período máximo de 10 minutos. Inclua esse parâmetro de alternância na chamada do cmdlet para desativar a lógica de repetição padrão.

Perfil

Especifica qual perfil carregar do arquivo de configuração. Este parâmetro espera um nome de perfil diferenciado por maiúsculas e minúsculas existente no arquivo de configuração.

Região

Especifica o ID da Região com o qual fazer chamadas. Por exemplo: us-phoenix-1 ou ap-singapore-1.

TimeOutInMillis

Especifica o tempo máximo de espera, em milissegundos, para que a solicitação da API seja concluída. O valor padrão é 100.000 millissegundos (100 segundos).

AuthType

Define o tipo de autenticação a ser usado para fazer solicitações de API. Por padrão, é utilizada a Chave de API do arquivo de configuração. Os valores válidos são ApiKey ou InstancePrincipal.

Entrada e Saída do Cmdlet

Esta seção descreve como os Cmdlets do OCI processam entrada e saída.

Entrada do Cmdlet

Os Cmdlets do OCI atualmente aceitam entradas de parâmetros de linha de comando ou por meio de pipeline por nomes de propriedade. Para ver um exemplo sobre como informar entradas por meio de pipeline por nome de propriedade, consulte esta amostra.

Saída do Cmdlet

Por padrão, os Cmdlets do OCI retorna apenas o corpo de resposta da API encapsulado em um tipo .NET associado. Para casos de uso que exigem que os usuários inspecionem a resposta completa da API, incluindo os cabeçalhos de resposta, use o parâmetro de alternância FullResponse na chamada DO cmdlet.

No exemplo a seguir, a operação GetConfiguration no serviço OCI Audit retorna um recurso Configuration no corpo da resposta.

Observação

Para executar o exemplo a seguir, importe 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;}

No exemplo de saída acima, a chamada padrão retorna apenas o objeto .NET que encapsula o corpo da resposta da API.

Para obter um objeto de saída que inclua a resposta completa da API, inclua o parâmetro -FullResponse na chamada do cmdlet. Por exemplo:

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

Chamadas Assíncronas

Para APIs da Oracle Cloud que retornam uma resposta de solicitação de trabalho assíncrona, com opc-work-request-id no cabeçalho da resposta e sem corpo da resposta, os Cmdlets PowerShell da OCI retornam um objeto Oci.PSModules.Common.Cmdlets.WorkRequest contendo a propriedade OpcWorkRequestId.

Por exemplo:


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

Tratamento de Erros

Se ocorrer um erro durante a execução de um Cmdlet do OCI, o cmdlet emitirá um erro de encerramento com um registro de erro contendo a exceção e uma mensagem de erro sobre a causa subjacente.

Documentação do Oracle Cloud Infrastructure