定義を作成する

  • [アーティクル]

名前空間: microsoft.graph

重要

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

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

アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。 アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。

アクセス許可の種類 アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント) AccessReview.ReadWrite.All
委任 (個人用 Microsoft アカウント) サポートされていません。
アプリケーション AccessReview.ReadWrite.All

サインインしているユーザーは、アクセス レビューの作成を許可するディレクトリ ロールにも存在する必要があります。 詳細については、 アクセス レビューのロールとアクセス許可の要件に関するページを参照してください。

HTTP 要求

POST /identityGovernance/accessReviews/definitions

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須。
Content-type application/json. 必須です。

要求本文

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

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

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

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

メモ： レビュー担当者が stageSettings プロパティを使用して割り当てられている場合、このプロパティの値は無視されます。
スコープ 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"
      }
    ]
  }
}