Mit Cmdlets arbeiten

In diesem Abschnitt wird beschrieben, wie die OCI-Module für PowerShell-Cmdlets verwendet werden.

Die Cmdlets der OCI-PowerShell-Module basieren auf dem Oracle Cloud Infrastructure-SDK für .NET. Diese Cmdlets führen Aufrufe an Oracle Cloud Infrastructure-REST-APIs mit den übergebenen Cmdlet-Parameterwerten durch.

Hinweis

Cmdlet-Parameter sind nach den jeweiligen in der API-Referenz aufgelisteten REST-API-Parametern benannt.

Die OCI-REST-APIs verwenden HTTPS-Anforderungen und -Antworten. Weitere Informationen finden Sie unter Informationen zur API.

Cmdlet-Discovery

OCI-Cmdlets werden nach einem Muster Verb -Substantiv benannt, wobei Verb den Vorgang darstellt, der bei der durch das Substantiv gekennzeichneten Ressource ausgeführt wurde. Letzteres umfasst in dieser Regel den Servicenamen gefolgt von dem Namen der Ressource im jeweiligen Service.

Beispiel: Der folgende Befehl gibt alle für die Arbeit mit einer Compute-Instanzressourcen im Compute-Service, der Teil des OCI-Core-Moduls PowerShell ist, verfügbaren Cmdlets zurück:

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

Hinweis

Mit dem Standard-Get-Befehl können Cmdlets in beliebigen Modulen gefunden werden.

Beispiel-Cmdlet

Dieses Beispiel zeigt, wie Sie ein einfaches OCI-Cmdlet aufrufen, das den Vorgang GetNamespace des OCI-Object Storage-Service aufruft. Dieser Vorgang gibt den Namen des Object Storage-Namespace für den Benutzer zurück, der die Anforderung gestellt hat.

Hinweis

Installieren und importieren Sie den ObjectStorage-Service, bevor Sie dieses Beispiel ausprobieren. Weitere Informationen finden Sie unter Installation.

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

Cmdlet-Hilfe

Um Hilfeinformationen für ein Cmdlet abzurufen, verwenden Sie das Cmdlet Get-Help, und übergeben Sie den Namen des Cmdlets als Parameter.

Hinweis

Um detailliertere Hilfeinformationen zu erhalten, verwenden Sie den Parameter -Full.

Dieses Beispiel zeigt die Hilfeausgabe für das 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

Allgemeine Parameter

In diesem Abschnitt werden die optionalen globalen Cmdlet-Parameter beschrieben, die allen Cmdlets in beliebigen OCI-PowerShell-Servicemodulen gemeinsam sind.

ConfigFile

Pfad zur Konfigurationsdatei, die Zugangsdaten für Oracle Cloud bereitstellt.

Endpoint

Gibt den Serviceendpunkt an, der für OCI-API-Aufrufe verwendet werden soll, einschließlich aller erforderlichen API-Versionspfade. Beispiel: https://audit.us-ashburn-1.oraclecloud.com

FullResponse

Standardmäßig geben OCI-Cmdlets den Antwortbody des REST-API-Vorgangs aus. Wenn der FullResponse-Switch-Parameter integriert wird, deutet dies darauf hin, dass das Cmdlet die vollständige Antwort ausgeben soll, die vom API-Vorgang zurückgegeben wird. Diese Antwort ist in einen entsprechenden .NET-Typ gewrappt (ein Objekt, das zusätzlich zu einem optionalen Antwortbody API-Antwortheader enthält).

NoRetry

Ein Switch-Parameter zur Deaktivierung der Standardwiederholungslogik für Aufrufe an Services.

Standardmäßig wiederholen OCI-PowerShell-Module nicht erfolgreiche API-Aufrufe, die die Statuscodes 400, 401, 404, 409, 429 und 500 zurückgeben. Wiederholungsversuche verwenden einen exponentiellen Backoff-Algorithmus mit maximal 5 Versuchen über eine maximale Zeitspanne von 10 Minuten. Fügen Sie diesen Switch-Parameter in den Cmdlet-Aufruf ein, um die Standardwiederholungslogik zu deaktivieren.

Profile

Gibt an, welches Profil aus der Konfigurationsdatei geladen werden soll. Dieser Parameter erwartet einen Profilnamen, bei dem Groß-/Kleinschreibung beachtet wird und der in der Konfigurationsdatei existiert.

Region

Gibt die Regions-ID der Region an, für die Aufrufe durchgeführt werden sollen. Beispiel: us-phoenix-1 oder ap-singapore-1.

TimeOutInMillis

Gibt die maximale Wartezeit in Millisekunden für den Abschluss der API-Anforderung an. Der Standardwert ist 100.000 Millisekunden (100 Sekunden).

AuthType

Definiert den Authentifizierungstyp, der für API-Anforderungen verwendet werden soll. Standardmäßig wird der API-Schlüssel in der Konfigurationsdatei verwendet. Gültige Werte sind ApiKey und InstancePrincipal.

Cmdlet-Eingabe und -Ausgabe

In diesem Abschnitt wird beschrieben, wie die OCI-Cmdlets die Ein- und Ausgabe verarbeiten.

Cmdlet-Eingabe

OCI-Cmdlets akzeptieren derzeit Eingaben aus Befehlszeilenparametern und Pipelineeingaben als Eigenschaftsnamen. Ein Beispiel für die Übergabe von Pipelineeingaben als Eigenschaftsname finden Sie hier.

Cmdlet-Ausgabe

Standardmäßig geben OCI-Cmdlets nur den API-Antwortbody zurück, der in einem entsprechenden .NET-Typ gekapselt ist. Für Anwendungsfälle, bei denen die Benutzer die vollständige API-Antwort einschließlich der Antwortheader prüfen müssen, verwenden Sie den FullResponse-Switch-Parameter im Cmdlet-Aufruf.

Im folgenden Beispiel gibt der GetConfiguration-Vorgang im OCI Audit-Service eine Configuration-Ressource im Antwortbody zurück.

Hinweis

Um folgendes Beispiel auszuführen, importieren Sie 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 der obigen Beispielausgabe gibt der Standardaufruf nur das .NET-Objekt zurück, das den API-Antwortbody kapselt.

Um ein Ausgabeobjekt abzurufen, das die vollständige API-Antwort enthält, fügen Sie den Parameter -FullResponse in den Cmdlet-Aufruf ein. Beispiel:

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

Asynchrone Aufrufe

Bei Oracle Cloud-APIs, die eine asynchrone Arbeitsanforderungsantwort mit opc-work-request-id im Antwortheader und keinem Antwortbody zurückgeben, geben OCI-PowerShell-Cmdlets ein Oci.PSModules.Common.Cmdlets.WorkRequest-Objekt zurück, welches die Eigenschaft OpcWorkRequestId enthält.

Beispiel:


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

Fehlerbehandlung

Wenn beim Ausführen eines OCI-Cmdlets ein Fehler auftritt, löst das Cmdlet einen Beendigungsfehler mit einem Fehlerdatensatz aus, der die Ausnahme und eine Fehlermeldung über die zugrunde liegende Ursache enthält.

Oracle Cloud Infrastructure - Dokumentation