Erstellen von historyDefinitions

Namespace: microsoft.graph

Erstellen Sie ein neues accessReviewHistoryDefinition-Objekt .

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) AccessReview.ReadWrite.All Nicht verfügbar.
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung AccessReview.ReadWrite.All Nicht verfügbar.

In delegierten Szenarien muss der angemeldete Benutzer mindestens über eine der folgenden Microsoft Entra Rollen verfügen.

Schreiben von Zugriffsüberprüfungen für eine Gruppe oder App Schreiben von Zugriffsüberprüfungen für eine Microsoft Entra Rolle
Benutzeradministrator
Identity Governance-Administrator
Identity Governance-Administrator
Mit privilegierter Rolle Administrator

HTTP-Anforderung

POST /identityGovernance/accessReviews/historyDefinitions

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.
Content-Type application/json. Erforderlich.

Anforderungstext

Geben Sie im Anforderungstext eine JSON-Darstellung des accessReviewHistoryDefinition-Objekts an.

Die folgende Tabelle zeigt die erforderlichen Eigenschaften, die zum Erstellen einer accessReviewHistoryDefinition verwendet werden.

Eigenschaft Typ Beschreibung
displayName String Name für die Datensammlung des Zugriffsüberprüfungsverlaufs. Erforderlich.
reviewHistoryPeriodStartDateTime DateTimeOffset Ein Zeitstempel. Überprüfungen, die am oder nach diesem Datum beginnen, werden in die abgerufenen Verlaufsdaten aufgenommen. Nur erforderlich, wenn scheduleSettings nicht definiert ist.
reviewHistoryPeriodEndDateTime DateTimeOffset Ein Zeitstempel. Überprüfungen, die am oder vor diesem Datum beginnen, werden in die abgerufenen Verlaufsdaten aufgenommen. Nur erforderlich, wenn scheduleSettings nicht definiert ist.
Bereiche accessReviewQueryScope-Sammlung Wird verwendet, um zu filtern, welche Überprüfungen in den abgerufenen Verlaufsdaten enthalten sind. Ruft Überprüfungen ab, deren Bereich mit diesem bereitgestellten Bereich übereinstimmt. Erforderlich.
Weitere Informationen finden Sie unter Unterstützte Bereichsabfragen für accessReviewHistoryDefinition.
scheduleSettings accessReviewHistoryScheduleSettings Wird noch nicht unterstützt. Die Einstellungen für eine Definitionsreihe mit dem Verlauf der wiederkehrenden Zugriffsüberprüfung. Nur erforderlich, wenn reviewHistoryPeriodStartDateTime oder reviewHistoryPeriodEndDateTime nicht definiert sind.

Unterstützte Bereichsabfragen für accessReviewHistoryDefinition

Die scopes-Eigenschaft von accessReviewHistoryDefinition basiert auf accessReviewQueryScope, einer Ressource, mit der Sie verschiedene Ressourcen in ihrer Abfrageeigenschaft konfigurieren können. Diese Ressourcen stellen dann den Bereich der Verlaufsdefinition dar und geben den Typ der Überprüfungsverlaufsdaten vor, die in der herunterladbaren CSV-Datei enthalten sind, die beim Erstellen der accessReviewHistoryInstances der Verlaufsdefinition generiert wird.

Der $filter Abfrageparameter mit dem contains Operator wird für die scope-Eigenschaft von accessReviewScheduleDefinition unterstützt. Verwenden Sie das folgende Format für die Anforderung:

/identityGovernance/accessReviews/definitions?$filter=contains(scope/microsoft.graph.accessReviewQueryScope/query, '{object}')

Der {object} kann einen der folgenden Werte aufweisen:

Wert Beschreibung
/groups Listen Sie alle accessReviewScheduleDefinition für einzelne Gruppen auf (schließt Definitionen aus, die für alle Microsoft 365-Gruppen mit Gästen gelten).
/groups/{group id} Listen Sie alle accessReviewScheduleDefinition für eine bestimmte Gruppe auf (schließt Definitionen aus, die für alle Microsoft 365-Gruppen mit Gästen gelten).
./members Listen Sie alle accessReviewScheduleDefinition auf, die auf alle Microsoft 365-Gruppen mit Gästen ausgerichtet sind.
accessPackageAssignments Listen Sie alle accessReviewScheduleDefinition-Instanzen für ein Zugriffspaket auf.
roleAssignmentScheduleInstances Listen Sie alle accessReviewScheduleDefinition-Instanzen für Prinzipale auf, die einer privilegierten Rolle zugewiesen sind.

Der $filter Abfrageparameter wird für accessReviewInactiveUserQueryScope oder principalResourceMembershipScope nicht unterstützt.

Antwort

Bei erfolgreicher Ausführung gibt die Methode den 201 Created Antwortcode und ein accessReviewHistoryDefinition-Objekt im Antworttext zurück.

Beispiele

Das folgende Beispiel zeigt, wie Sie eine Zugriffsüberprüfungsverlaufsdefinition erstellen, die auf Zugriffsüberprüfungen für Zugriffspakete und -gruppen ausgerichtet ist und zwischen dem Startdatum 01.01.2021 und dem Enddatum 04.05.2021 ausgeführt wird.

Anforderung

POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/historyDefinitions
Content-Type: application/json

{
  "displayName": "Last quarter's group reviews April 2021",
  "decisions": [
    "approve",
    "deny",
    "dontKnow",
    "notReviewed",
    "notNotified"
  ],
  "reviewHistoryPeriodStartDateTime": "2021-01-01T00:00:00Z",
  "reviewHistoryPeriodEndDateTime": "2021-04-30T23:59:59Z",
  "scopes": [
    {
      "@odata.type": "#microsoft.graph.accessReviewQueryScope",
      "queryType": "MicrosoftGraph",     
      "query": "/identityGovernance/accessReviews/definitions?$filter=contains(scope/query, 'accessPackageAssignments')",
      "queryRoot": null
    },  
    {
      "@odata.type": "#microsoft.graph.accessReviewQueryScope",
      "queryType": "MicrosoftGraph",     
      "query": "/identityGovernance/accessReviews/definitions?$filter=contains(scope/query, '/groups')",
      "queryRoot": null
    }
  ]
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.type": "#microsoft.graph.accessReviewHistoryDefinition",
    "id": "b2cb022f-b7e1-40f3-9854-c65a40861c38",
    "displayName": "Last quarter's group reviews April 2021",
    "reviewHistoryPeriodStartDateTime": "2021-01-01T00:00:00Z",
    "reviewHistoryPeriodEndDateTime": "2021-04-30T23:59:59Z",
    "decisions": [
        "approve",
        "deny",
        "dontKnow",
        "notReviewed",
        "notNotified"
    ],
    "status": "requested",
    "createdDateTime": "2021-04-14T00:22:48.9392594Z",
    "createdBy": {
        "id": "957f1027-c0ee-460d-9269-b8444459e0fe",
        "displayName": "MOD Administrator",
        "userPrincipalName": "admin@contoso.com"
    },
    "scopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "queryType": "MicrosoftGraph",
            "query": "/identityGovernance/accessReviews/definitions?$filter=contains(scope/query, 'accessPackageAssignments')",
            "queryRoot": null
        },
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "queryType": "MicrosoftGraph",
            "query": "/identityGovernance/accessReviews/definitions?$filter=contains(scope/query, '/groups')",
            "queryRoot": null
        }
    ]
}