定義を作成する

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

新しい accessReviewScheduleDefinition オブジェクトを作成します。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ❌

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。

アクセス許可の種類 最小特権アクセス許可 特権の高いアクセス許可
委任 (職場または学校のアカウント) AccessReview.ReadWrite.All 注意事項なし。
委任 (個人用 Microsoft アカウント) サポートされていません。 サポートされていません。
アプリケーション AccessReview.ReadWrite.All 注意事項なし。

委任されたシナリオの場合、サインインしているユーザーは、次のMicrosoft Entraロールの少なくとも 1 つを持っている必要があります。

グループまたはアプリのアクセス レビューを書き込む Microsoft Entra ロールの書き込みアクセス レビュー
ユーザー管理者
ID ガバナンス管理者		 ID ガバナンス管理者
特権ロール管理者

HTTP 要求

POST /identityGovernance/accessReviews/definitions

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。
Content-type application/json. 必須です。

要求本文

要求本文で、 accessReviewScheduleDefinition オブジェクトの JSON 表現を指定します。

次の表は、accessReview の作成に使用できるプロパティを示しています。

プロパティ 型 説明
additionalNotificationRecipients accessReviewNotificationRecipientItem コレクション アクセス レビューの進行状況を通知する追加のユーザーまたはグループ メンバーの一覧を定義します。
descriptionForAdmins String 管理者に提供されるレビューのコンテキスト。 必須です。
descriptionForReviewers String 電子メール通知でレビュー担当者に提供されるレビューのコンテキスト。 Email通知では、最大 256 文字がサポートされます。 必須です。
displayName String アクセス レビュー シリーズの名前。 必須です。
fallbackReviewers accessReviewReviewerScope コレクション 指定された場合、フォールバック レビュー担当者は、プライマリ レビュー担当者が存在しない場合にレビューを完了するように求められます。 たとえば、マネージャーがとしてreviewers選択され、レビュー対象のプリンシパルにMicrosoft Entra IDにマネージャーがいない場合、フォールバック レビュー担当者はそのプリンシパルを確認するように求められます。

メモ： フォールバック レビュー担当者が stageSettings プロパティを使用して割り当てられている場合、このプロパティの値は無視されます。
instanceEnumerationScope accessReviewScope すべてのグループレビューの場合、これにより、レビューされるグループの範囲が決まります。 accessReviewScope を参照し、アクセス レビュー定義のスコープを構成する方法についても説明します。
レビュー accessReviewReviewerScope コレクション レビュー担当者を定義します。 何も指定されていない場合、レビューは自己レビューです (ユーザーは自分のアクセス権を確認します)。 レビュー担当者を割り当てるオプションの例については、「Microsoft Graph APIを使用してレビュー担当者をアクセス レビュー定義に割り当てる」を参照してください。

メモ： レビュー担当者が stageSettings プロパティを使用して割り当てられている場合、このプロパティの値は無視されます。
scope accessReviewScope アクセス権がレビューされるエンティティを定義します。 accessReviewScope を参照し、アクセス レビュー定義のスコープを構成する方法についても説明します。 必須です。
stageSettings accessReviewStageSettings コレクション アクセス レビュー シリーズの各インスタンスに含まれるステージの数を定義します。 ステージは dependsOn プロパティに基づいて順番に作成されます。 各ステージには、レビュー担当者、フォールバック レビュー担当者、設定のセットが異なる場合があります。

このプロパティを定義すると、 accessReviewScheduleDefinition オブジェクトとその settings プロパティ内の対応する値の代わりに、その値が使用されます。 省略可能です。
settings accessReviewScheduleSettings アクセス レビュー シリーズの設定。 ここで繰り返しが決定されます。 「accessReviewScheduleSettings」を参照してください。
backupReviewers (非推奨) accessReviewReviewerScope コレクション このプロパティは 、fallbackReviewers に置き換えられました。 ただし、 backupReviewers または fallbackReviewers を指定すると、同じ値が他のプロパティに自動的に設定されます。

応答

成功した場合、このメソッドは 201 Created 応答コードと、応答本文の accessReviewScheduleDefinition オブジェクトを返します。

例

例 1: グループに対するアクセス レビューを作成する

次の例では、次の設定でアクセス レビューを作成します。

  • このレビューでは、 ID を02f3bafb-448c-487c-88c2-5fd65ce49a41持つグループのすべてのメンバーがレビューされます。
  • ユーザー ID398164b1-5196-49dd-ada2-364b49f99b27 を持つ特定のユーザーがレビュー担当者です。
  • 毎週繰り返され、無期限に続きます。

要求

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Test create",
  "descriptionForAdmins": "New scheduled access review",
  "descriptionForReviewers": "If you have any questions, contact jerry@contoso.com",
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/02f3bafb-448c-487c-88c2-5fd65ce49a41/transitiveMembers",
    "queryType": "MicrosoftGraph"
  },
  "reviewers": [
    {
      "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
      "queryType": "MicrosoftGraph"
    }
  ],  
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": false,
    "defaultDecision": "None",
    "instanceDurationInDays": 1,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "weekly",
        "interval": 1
      },
      "range": {
        "type": "noEnd",
        "startDate": "2020-09-08T12:02:30.667Z"
      }
    }
  }
}

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "id": "29f2d16e-9ca6-4052-bbfe-802c48944448",
  "displayName": "Test create",
  "createdDateTime": "0001-01-01T00:00:00Z",
  "lastModifiedDateTime": "0001-01-01T00:00:00Z",
  "status": "NotStarted",
  "descriptionForAdmins": "Test create",
  "descriptionForReviewers": "Test create",
  "instanceEnumerationScope": null,
  "createdBy": {
    "id": "957f1027-c0ee-460d-9269-b8444459e0fe",
    "displayName": "MOD Administrator",
    "userPrincipalName": "admin@contoso.com"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/b74444cb-038a-4802-8fc9-b9d1ed0cf11f/transitiveMembers",
    "queryType": "MicrosoftGraph"
  },
  "reviewers": [
    {
      "query": "/users/7eae986b-d425-48b2-adf2-3c777f4444f3",
      "queryType": "MicrosoftGraph",
      "queryRoot": "decisions"
    }
  ],  
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": false,
    "defaultDecision": "None",
    "instanceDurationInDays": 1,
    "autoApplyDecisionsEnabled": false,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "weekly",
        "interval": 1,
        "month": 0,
        "dayOfMonth": 0,
        "daysOfWeek": [],
        "firstDayOfWeek": "sunday",
        "index": "first"
      },
      "range": {
        "type": "noEnd",
        "numberOfOccurrences": 0,
        "recurrenceTimeZone": null,
        "startDate": "2020-09-08",
        "endDate": null
      }
    },
  "applyActions": []
  },
  "additionalNotificationRecipients": []
}

例 2: 非アクティブなゲスト ユーザーを持つすべてのチームに対してアクセス レビューを作成する

次の例では、次の設定でアクセス レビューを作成します。

  • このレビューでは、非アクティブなゲスト ユーザーを持つすべてのチームがレビューされます。 非アクティブ期間は、アクセス レビューの開始日から 30 日間です。
  • グループ所有者はレビュー担当者であり、フォールバック レビュー担当者が割り当てられます。
  • 四半期ごとの 3 日目に繰り返され、無期限に続きます。
  • autoApplyDecisionsEnabled は に true 設定され、 defaultDecision は に Deny設定されています。

要求

要求本文で、 accessReviewScheduleDefinition オブジェクトの JSON 表現を指定します。

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Review inactive guests on teams",
  "descriptionForAdmins": "Control guest user access to our teams.",
  "descriptionForReviewers": "Information security is everyone's responsibility. Review our access policy for more.",
  "instanceEnumerationScope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team')')",
    "queryType": "MicrosoftGraph"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph",
    "inactiveDuration": "P30D"
    },
  "reviewers": [
    {
      "query": "./owners",
      "queryType": "MicrosoftGraph"
    }
  ],
  "fallbackReviewers": [
    {
      "query": "/users/fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f",
      "queryType": "MicrosoftGraph"
    }
  ],
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "recommendationsEnabled": true,
    "instanceDurationInDays": 3,
    "recurrence": {
      "pattern": {
        "type": "absoluteMonthly",
        "dayOfMonth": 5,
        "interval": 3
      },
      "range": {
        "type": "noEnd",
        "startDate": "2020-05-04T00:00:00.000Z"
      }
    },
    "defaultDecisionEnabled": true,
    "defaultDecision": "Deny",
    "autoApplyDecisionsEnabled": true
  }
}

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions/$entity",
  "id": "b0966e21-a01e-43c9-8f8b-9ba30ed5710a",
  "displayName": "Review inactive guests on teams",
  "createdDateTime": "2021-05-04T18:27:02.6719849Z",
  "lastModifiedDateTime": "2021-05-04T18:27:24.0889623Z",
  "status": "InProgress",
  "descriptionForAdmins": "Control guest user access to our teams.",
  "descriptionForReviewers": "Information security is everyone's responsibility. Review our access policy for more.",
  "createdBy": {
    "id": "fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f",
    "displayName": "MOD Administrator",
    "userPrincipalName": "admin@contoso.com"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph",
    "queryRoot": null,
    "inactiveDuration": "P30D"
  },
  "instanceEnumerationScope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team'))&$count=true",
    "queryType": "MicrosoftGraph",
    "queryRoot": null
  },
  "reviewers": [
    {
      "query": "./owners",
      "queryType": "MicrosoftGraph",
      "queryRoot": null
    }
  ],
  "backupReviewers": [],
  "fallbackReviewers": [
    {
      "query": "/users/fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f",
      "queryType": "MicrosoftGraph",
      "queryRoot": null
    }
  ],
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": true,
    "defaultDecision": "Deny",
    "instanceDurationInDays": 3,
    "autoApplyDecisionsEnabled": true,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "absoluteMonthly",
        "interval": 3,
        "month": 0,
        "dayOfMonth": 5,
        "daysOfWeek": [],
        "firstDayOfWeek": "sunday",
        "index": "first"
      },
      "range": {
        "type": "noEnd",
        "numberOfOccurrences": 0,
        "recurrenceTimeZone": null,
        "startDate": "2021-05-05",
        "endDate": null
      }
    },
    "applyActions": []
  },
  "additionalNotificationRecipients": []
}

例 3: アプリケーションに対するすべてのユーザーのアクセス レビューを作成する

次の例では、次の設定でアクセス レビューを作成します。

  • レビューでは、アプリケーションへのユーザー アクセスがレビューされます。
  • ユーザー マネージャーはレビュー担当者であり、フォールバック レビュー担当者はグループのメンバーです。
  • 半期が繰り返され、startDate から 1 年が終了します。

要求

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Review employee access to LinkedIn",
  "descriptionForAdmins": "Review employee access to LinkedIn",
  "scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/users",
        "queryType": "MicrosoftGraph"
      }
    ],
    "resourceScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/servicePrincipals/bae11f90-7d5d-46ba-9f55-8112b59d92ae",
        "queryType": "MicrosoftGraph"
      }
    ]
  },
  "reviewers": [
    {
      "query": "./manager",
      "queryType": "MicrosoftGraph",
      "queryRoot": "decisions"
    }
  ],
  "backupReviewers": [
    {
      "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
      "queryType": "MicrosoftGraph"
    }
  ],
  "fallbackReviewers": [
    {
      "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
      "queryType": "MicrosoftGraph"
    }
  ],
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": true,
    "defaultDecision": "Recommendation",
    "instanceDurationInDays": 180,
    "autoApplyDecisionsEnabled": true,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "absoluteMonthly",
        "interval": 6,
        "dayOfMonth": 0
      },
      "range": {
        "type": "numbered",
        "startDate": "2021-05-05",
        "endDate": "2022-05-05"
      }
    }
  }
}

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions/$entity",
  "id": "1f79f34b-8667-40d9-875c-893b630b3dec",
  "scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/users"
      }
    ],
    "resourceScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/servicePrincipals/bae11f90-7d5d-46ba-9f55-8112b59d92ae"
      }
    ]
  },
  "reviewers": [
    {
      "query": "./manager"
    }
  ],
  "fallbackReviewers": [
    {
      "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers"
    }
  ]
}

例 4: 複数のステージを持つグループに対してアクセス レビューを作成する

次の例では、次の設定でアクセス レビューを作成します。

  • このレビューでは、 ID を02f3bafb-448c-487c-88c2-5fd65ce49a41持つグループのすべてのメンバーがレビューされます。
  • これには、次の 2 つのステージがあります。
    • ユーザー ID398164b1-5196-49dd-ada2-364b49f99b27 を持つ特定のユーザーは、最初のステージのレビュー担当者です。
    • ユーザー マネージャーは、2 番目のステージのレビュー担当者とフォールバック レビュー担当者です。
  • 毎週繰り返され、無期限に続きます。

要求

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Group Multi-stage Access Review",
  "descriptionForAdmins": "New scheduled access review",
  "descriptionForReviewers": "If you have any questions, contact jerry@contoso.com",
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/02f3bafb-448c-487c-88c2-5fd65ce49a41/transitiveMembers",
    "queryType": "MicrosoftGraph"
  },
  "stageSettings": [
    {
      "stageId": "1",
      "durationInDays": 2,
      "recommendationsEnabled": false,
      "decisionsThatWillMoveToNextStage": [
          "NotReviewed",
          "Approve"
      ],
      "reviewers": [
        {
          "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
          "queryType": "MicrosoftGraph"
        }
      ]
    },
    {
      "stageId": "2",
      "dependsOn": [
          "1"
      ],
      "durationInDays": 2,
      "recommendationsEnabled": true,
      "reviewers": [
        {
          "query": "./manager",
          "queryType": "MicrosoftGraph",
          "queryRoot": "decisions"
        }
      ],
      "fallbackReviewers": [
        {
          "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
          "queryType": "MicrosoftGraph"
        }
      ]
    }
  ],
  "settings": {
    "instanceDurationInDays": 4,
    "recurrence": {
      "pattern": {
        "type": "weekly",
        "interval": 1
      },
      "range": {
        "type": "noEnd",
        "startDate": "2020-09-08T12:02:30.667Z"
      }
    },
    "decisionHistoriesForReviewersEnabled": true
  }
}

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "id": "29f2d16e-9ca6-4052-bbfe-802c48944448",
  "displayName": "Group Multi-stage Access Review",
  "createdBy": {
    "id": "957f1027-c0ee-460d-9269-b8444459e0fe"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/b74444cb-038a-4802-8fc9-b9d1ed0cf11f/transitiveMembers"
  },
  "stageSettings": [
    {
      "stageId": "1",
      "durationInDays": 2,
      "recommendationsEnabled": false,
      "decisionsThatWillMoveToNextStage": [
          "NotReviewed",
          "Approve"
      ],
      "reviewers": [
        {
          "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
          "queryType": "MicrosoftGraph"
        }
      ]
    },
    {
      "stageId": "2",
      "dependsOn": [
          "1"
      ],
      "durationInDays": 2,
      "recommendationsEnabled": true,
      "reviewers": [
        {
          "query": "./manager",
          "queryType": "MicrosoftGraph",
          "queryRoot": "decisions"
        }
      ],
      "fallbackReviewers": [
        {
          "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
          "queryType": "MicrosoftGraph"
        }
      ]
    }
  ]
}

例 5: ユーザーからグループへの所属に関する分析情報と推奨事項のユーザー サインインを含むグループに対するアクセス レビューを作成する

次の例では、次の設定でアクセス レビューを作成します。

  • このレビューでは、 ID を02f3bafb-448c-487c-88c2-5fd65ce49a41持つグループのすべてのメンバーがレビューされます。
  • ユーザー ID398164b1-5196-49dd-ada2-364b49f99b27 を持つ特定のユーザーがレビュー担当者です。
  • 毎週繰り返され、無期限に続きます。
  • ユーザーとグループの両方の所属とユーザー サインインは、レビュー担当者の分析情報です。

要求

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "Test create",
    "descriptionForAdmins": "New scheduled access review",
    "descriptionForReviewers": "If you have any questions, contact jerry@contoso.com",
    "scope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/groups/02f3bafb-448c-487c-88c2-5fd65ce49a41/transitiveMembers",
        "queryType": "MicrosoftGraph"
    },
    "reviewers": [
        {
            "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
            "queryType": "MicrosoftGraph"
        }
    ],
    "settings": {
        "instanceDurationInDays": 1,
        "recurrence": {
            "pattern": {
                "type": "weekly",
                "interval": 1
            },
            "range": {
                "type": "noEnd",
                "startDate": "2020-09-08T12:02:30.667Z"
            }
        },
        "recommendationInsightSettings": [
            {
                "@odata.type": "#microsoft.graph.userLastSignInRecommendationInsightSetting",
                "recommendationLookBackDuration": "P30D",
                "signInScope": "tenant"
            },
            {
                "@odata.type": "#microsoft.graph.groupPeerOutlierRecommendationInsightSettings"
            }
        ]
    }
}

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "id": "29f2d16e-9ca6-4052-bbfe-802c48944448",
  "displayName": "Test create",
  "createdBy": {
    "id": "957f1027-c0ee-460d-9269-b8444459e0fe"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/b74444cb-038a-4802-8fc9-b9d1ed0cf11f/transitiveMembers"
  },
  "reviewers": [
    {
      "query": "/users/7eae986b-d425-48b2-adf2-3c777f4444f3"
    }
  ],
  "settings": {
    "recommendationInsightSettings": [
      {
        "@odata.type": "#microsoft.graph.userLastSignInRecommendationInsightSetting",
        "recommendationLookBackDuration": "P30D",
        "signInScope": "tenant"
      },
      {
        "@odata.type": "#microsoft.graph.groupPeerOutlierRecommendationInsightSettings"
      }
    ]
  }
}