Navigieren in der Microsoft Graph-Befehlszeilenschnittstelle (CLI)

Artikel
11/07/2024

Die Microsoft Graph-API ist riesig und wächst ständig. Daher ist die Anzahl der Befehle in der Microsoft Graph-Befehlszeilenschnittstelle (CLI) ebenfalls groß. Die Suche nach dem richtigen Befehl für das, was Sie erreichen möchten, kann eine Herausforderung sein, insbesondere wenn Sie noch nicht mit Microsoft Graph vertraut sind. In diesem Thema werden einige Möglichkeiten zum Suchen eines bestimmten Befehls erläutert.

Hinweis

Einige Anforderungen für Microsoft Entra-Ressourcen erfordern die Verwendung erweiterter Abfragefunktionen. Wenn Sie eine Antwort erhalten, die auf eine ungültige Anforderung, eine nicht unterstützte Abfrage oder eine Antwort mit unerwarteten Ergebnissen hinweist, kann es möglich sein, dass die Anforderung erfolgreich ist, einschließlich des $count Abfrageparameters und ConsistencyLevel des Headers. Ausführliche Informationen und Beispiele finden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Befehlsbenennungskonventionen

Die Befehle in der CLI werden direkt aus der REST-API generiert, sodass die Namen von der API beeinflusst werden. Sie müssen die Details der API nicht verstehen, um die Microsoft Graph CLI verwenden zu können, aber es ist hilfreich, die Benennungskonvention zu verstehen.

Die Befehle der Microsoft Graph-Befehlszeilenschnittstelle stellen Ressourcen in Microsoft Graph und die Aktionen dar, die für diese Ressourcen ausgeführt werden können. Die allgemeine Struktur der Befehle folgt diesem Muster:

mgc <path-to-resource> <action>

Ist <path-to-resource> mindestens ein Befehl, der der URL-Struktur der Ziel-API folgt. ist <action> der letzte Befehl in der Sequenz und gibt die Aktion an, die für die Zielressource ausgeführt werden soll.

Pfad zu Ressourcenbefehlen

Der Pfad zur Zielressource wird erstellt, indem ein oder mehrere Befehle sequenziert werden, um die URL zur Ressource darzustellen, wie von der REST-API angegeben. Für eine einfache API wie GET /mereicht ein einzelner Befehl (me) aus, um den Pfad darzustellen.

Sehen Sie sich als Nächstes ein komplexeres Beispiel an: die API zum Abrufen von Nachrichten. Sehen Sie sich die HTTP-Anforderungen für diese API an. Wenn Sie die Anforderungen mit /me in der URL ignorieren, gibt es zwei weitere Möglichkeiten, diese API aufzurufen.

GET /users/{id | userPrincipalName}/messages/{id}
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages/{id}

Die entsprechenden CLI-Befehle werden den Segmenten in den URLs zugeordnet. Die Segmente der ersten URL werden beispielsweise den folgenden Befehlen zugeordnet:

/users wird zugeordnet zu users
/{id | userPrincipalName} --user-id entspricht (mehr dazu unten)
/messages wird zugeordnet zu messages
/{id} wird zugeordnet zu --message-id

Wenn dies alles zusammengerechnet wird, wären users messages --user-id <user-id> --message-id <message-id>die entsprechenden Befehle .

Zugreifen auf ein Element in einer Sammlung

URL-Segmente in einer API, die ein Plural-Substantiv verwenden, geben eine Sammlung an. Wenn eine API auf ein bestimmtes Element in dieser Sammlung reagiert, enthält die URL ein Segment mit einer ID. Im vorherigen Beispiel werden die Segmente /users/{id | userPrincipalName} kombiniert, um auf einen bestimmten Benutzer in der Benutzersammlung zuzugreifen. Diese "ID-Segmente" werden in der Microsoft Graph CLI durch eine erforderliche ID-Option dargestellt, die wie --<name of resource>-idbenannt ist. Diese Optionen werden nach dem Aktionsbefehl angezeigt. Verwenden Sie die --help Option, um die erforderlichen Optionen für einen bestimmten Befehl anzuzeigen.

Aktionsbefehle

Bei grundlegenden REST-Vorgängen wird das Verb durch die HTTP-Methode bestimmt, die für die API verwendet wird.

HTTP-Methode	Befehlsverb	Beispiel
GET (einzelnes Element)	`get`	`mgc me get` API-Referenz
GET (Sammlung)	`list`	`mgc users list` API-Referenz
POST	`create`	`mgc me messages create` API-Referenz
PUT	`put`	`mgc drives items content put` API-Referenz
PATCH	`patch`	`mgc me events patch` API-Referenz
LÖSCHEN	`delete`	`mgc drives items delete` API-Referenz

Sehen Sie sich das Beispiel für die Get Message-API aus dem vorherigen Abschnitt an. Der Pfad zur Ressource wird durch users messagesdargestellt, und die HTTP-Methode für diese API ist GET, wodurch ein einzelnes Element zurückgegeben wird. Das bedeutet, dass der resultierende Befehl für diese API ist mgc users messages get --user-id <user-id> --message-id <message-id>.

Auflisten von Parametern

Nachdem Sie den richtigen Befehl gefunden haben, können Sie alle verfügbaren Parameter mithilfe der --help Option untersuchen. Der folgende Befehl listet beispielsweise alle verfügbaren Parameter für den mgc users messages get Befehl auf.

mgc users messages get --help

Suchen nach verfügbaren Befehlen

Manchmal reicht es nicht aus, nur die Namenskonventionen zu kennen, um den richtigen Befehl zu erraten. In diesem Fall können Sie die --help Option iterativ verwenden, um die verfügbaren Befehle in der CLI zu durchsuchen. Gibt beispielsweise die vollständige Liste der verfügbaren Befehle zurück, mgc --help die als erster Befehl in der Sequenz gültig sind. Sie können einen der verfügbaren Befehle auswählen und ihn dann dem vorherigen Befehl hinzufügen, um die nächste Befehlsstufe zu finden.

Beispiel

$ mgc --help
Description:
  Microsoft Graph CLI

Usage:
  mgc [command] [options] [[--] <additional arguments>...]]

Options:
  -?, -h, --help  Show help and usage information
  --version       Show version information

Commands:
  admin
  agreement-acceptances
  agreements
  app-catalogs
  applications
  ...

$ mgc applications --help
Description:
  Provides operations to manage the collection of application entities.

Usage:
  mgc applications [command] [options]

Options:
  -?, -h, --help  Show help and usage information

Commands:
  add-key                             Provides operations to call the addKey method.
  add-password                        Provides operations to call the addPassword method.
  app-management-policies             Provides operations to manage the appManagementPolicies property of the
                                      microsoft.graph.application entity.
  check-member-groups                 Provides operations to call the checkMemberGroups method.
  ...

Freigeben über