Azure Event Grid를 통해 Microsoft Graph API 변경 이벤트 수신(미리 보기)

  • 아티클

이 문서에서는 Microsoft Graph API에서 게시한 이벤트를 구독하는 단계를 설명합니다. 다음 표에서는 Graph API를 통해 이벤트를 사용할 수 있는 이벤트 원본을 나열합니다. 대부분의 리소스에서 생성, 업데이트 및 삭제를 발표하는 이벤트가 지원됩니다. 이벤트 원본에 대해 이벤트가 발생하는 리소스에 대한 자세한 내용은 Microsoft Graph API 변경 알림에서 지원되는 리소스를 참조하세요.

Important

이벤트를 Azure Event Grid로 보내는 Microsoft Graph API의 기능은 현재 공개 미리 보기 상태입니다. 질문이 있거나 지원이 필요한 경우 ask-graph-and-grid@microsoft.com(으)로 이메일을 보내주세요.

Microsoft 이벤트 원본 사용할 수 있는 이벤트 유형
Microsoft Entra ID Microsoft Entra 이벤트 유형
Microsoft Outlook Microsoft Outlook 이벤트 유형
Microsoft 365 그룹 대화
Microsoft Teams Microsoft Teams 이벤트 유형
Microsoft SharePoint 및 OneDrive
Microsoft SharePoint
보안 경고
Microsoft Conversations
Microsoft 유니버설 인쇄

Important

파트너 이벤트 기능에 익숙하지 않은 경우 파트너 이벤트 개요를 살펴봅니다.

Event Grid를 통해 Microsoft Graph API 원본의 이벤트를 구독해야 하는 이유는 무엇인가요?

Event Grid를 통해 Microsoft Graph API 이벤트를 구독하는 기능 외에도 유사한 알림(이벤트 아님)을 받을 수 있는 다른 옵션이 있습니다. 다음 요구 사항 중 하나 이상이 있는 경우 Microsoft Graph API를 사용하여 Event Grid에 이벤트를 전달하는 것이 좋습니다.

  • 리소스 변경에 대응하기 위해 Microsoft Entra ID, Outlook, Teams 등의 이벤트가 필요한 이벤트 기반 솔루션을 개발하고 있습니다. Event Grid에서 제공하는 강력한 이벤트 모델 및 게시-구독 기능이 필요합니다. Event Grid의 개요를 보려면 Event Grid 개념을 참조하세요.
  • Event Grid를 사용하여 단일 Graph API 구독을 통해 이벤트를 여러 대상으로 라우팅하려고 하며 여러 Graph API 구독을 관리하지 않으려고 합니다.
  • 이벤트의 일부 속성에 따라 이벤트를 다른 다운스트림 애플리케이션, 웹후크 또는 Azure 서비스로 라우팅해야 합니다. 예를 들어 사용자의 온보딩 및 오프보딩을 처리하는 특수 애플리케이션에 Microsoft.Graph.UserCreated 및 Microsoft.Graph.UserDeleted와 같은 이벤트 유형을 라우팅할 수 있습니다. 예를 들어 연락처 정보를 동기화하는 다른 애플리케이션으로 Microsoft.Graph.UserUpdated 이벤트를 보낼 수도 있습니다. Event Grid를 알림 대상으로 사용할 때 단일 Graph API 구독을 사용할 수 있습니다. 자세한 내용은 이벤트 필터링 및 이벤트 처리기를 참조하세요.
  • 상호 운용성은 사용자에게 중요합니다. CNCF의 CloudEvents 사양 표준을 사용하여 표준 방식으로 이벤트를 전달하고 처리하려고 합니다.
  • CloudEvents에서 제공하는 확장성 지원을 원합니다. 예를 들어 규격 시스템에서 이벤트를 추적하려는 경우 CloudEvents 확장 분산 추적을 사용합니다. CloudEvents 확장에 대해 자세히 알아봅니다.
  • 업계에서 채택한 검증된 이벤트 기반 접근 방식을 사용하려고 합니다.

Graph API 이벤트가 파트너 항목으로 전달되도록 설정

Microsoft Graph API SDK를 사용하여 Graph API 구독을 만들어 이 섹션에 제공된 샘플 링크의 단계를 수행하여 Event Grid 파트너 토픽에 이벤트를 전달하도록 Microsoft Graph API를 요청합니다. 사용 가능한 SDK 지원은 Microsoft Graph API SDK에 지원되는 언어를 참조하세요.

일반 전제 조건

Microsoft Graph API 구독을 만들고 갱신하는 애플리케이션을 구현하기 전에 이러한 일반적인 필수 조건을 충족해야 합니다.

선택한 프로그래밍 언어 및 사용하는 개발 환경과 관련된 다른 필수 구성 요소는 다음 섹션에 나오는 Microsoft Graph API 샘플 링크에서 찾을 수 있습니다.

Important

애플리케이션을 구현하기 위한 자세한 지침은 자세한 지침이 포함된 샘플 섹션에서 찾을 수 있지만 Event Grid를 사용하여 Microsoft Graph API 이벤트 전달과 관련된 중요한 추가 정보가 포함되어 있으므로 이 문서의 모든 섹션을 읽어야 합니다.

Microsoft Graph API 구독을 만드는 방법

Graph API 구독을 만들면 파트너 토픽이 만들어집니다. 매개 변수 notificationUrl에 다음 정보를 전달하여 생성할 파트너 토픽을 지정하고 새 Graph API 구독에 연결할 수 있습니다.

  • 파트너 토픽 이름
  • 파트너 토픽이 만들어지는 리소스 그룹 이름
  • 지역(위치)
  • Azure 구독

이러한 코드 샘플에서는 Graph API 구독을 만드는 방법을 보여줍니다. 생성, 업데이트 또는 삭제될 때 Microsoft Entra ID 테넌트의 모든 사용자로부터 이벤트를 수신하는 구독을 만드는 예제를 보여 줍니다.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
    "changeType": "Updated,Deleted,Created",
    "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "resource": "users",
    "expirationDateTime": "2024-03-31T00:00:00Z",
    "clientState": "secretClientValue"
}
  • changeType: 이벤트를 수신하려는 리소스 변경의 종류입니다. 유효한 값은 Updated, Deleted 및 Created입니다. 이러한 값 중 하나 이상을 쉼표로 구분하여 지정할 수 있습니다.
  • notificationUrl: 이벤트가 전송되는 파트너 토픽을 정의하는 데 사용되는 URI입니다. EventGrid:?azuresubscriptionid=<you-azure-subscription-id>&resourcegroup=<your-resource-group-name>&partnertopic=<the-name-for-your-partner-topic>&location=<the-Azure-region-name-where-you-want-the-topic-created> 패턴을 따라야 합니다. az account list-locations 명령을 실행하여 위치(Azure 지역이라고도 함) name을(를) 가져올 수 있습니다. 위치 표시 이름을 사용하지 마세요. 예를 들어 "미국 중서부"를 사용하지 마세요. 대신 westcentralus을 사용합니다. 
      az account list-locations
  • lifecycleNotificationUrl: microsoft.graph.subscriptionReauthorizationRequired 이벤트가 전송되는 파트너 토픽을 정의하는 데 사용되는 URI입니다. 이 이벤트는 Graph API 구독이 곧 만료된다는 것을 애플리케이션에 알립니다. URI는 Event Grid를 수명 주기 이벤트의 대상으로 사용하는 경우 위에서 설명한 notificationUrl과 동일한 패턴을 따릅니다. 이 경우 파트너 토픽은 notificationUrl에 지정된 항목과 동일해야 합니다.
  • resource: 상태 변경을 알리는 이벤트를 생성하는 리소스입니다.
  • expirationDateTime: 구독이 만료되어 이벤트 흐름이 중지되는 만료 시간입니다. RFC 3339에 지정된 형식을 준수해야 합니다. 리소스 종류별로 허용되는 최대 구독 길이 내에서 만료 시간을 지정해야 합니다.
  • 클라이언트 상태. 이 속성은 선택 사항입니다. 이벤트 전달 중에 이벤트 처리기 애플리케이션에 대한 호출을 확인하는 데 사용됩니다. 자세한 내용은 Graph API 구독 속성을 참조하세요.

Important

  • 파트너 토픽 이름은 동일한 Azure 지역 내에서 고유해야 합니다. 각 테넌트-애플리케이션 ID 조합은 최대 10개의 고유한 파트너 토픽을 만들 수 있습니다.

  • 솔루션을 개발할 때 특정 Graph API 리소스의 서비스 제한을 염두에 두어야 합니다.

  • lifecycleNotificationUrl 속성이 없는 기존 Graph API 구독은 수명 주기 이벤트를 수신하지 않습니다. lifecycleNotificationUrl 속성을 추가하려면 기존 구독을 삭제하고 구독을 만드는 동안 속성을 지정하는 새 구독을 만들어야 합니다.

참고 항목

애플리케이션이 프라이빗 미리 보기 중에 Graph API 구독을 생성하라는 요청에 x-ms-enable-features 헤더를 사용하는 경우 더 이상 필요하지 않으므로 제거해야 합니다.

Graph API 구독을 만든 후 Azure에서 파트너 토픽을 만듭니다.

Microsoft Graph API 구독 갱신

이벤트 흐름이 중지되지 않도록 Graph API 구독이 만료되기 전에 애플리케이션에서 갱신해야 합니다. 갱신 프로세스를 자동화하기 위해 Microsoft Graph API는 애플리케이션이 구독할 수 있는 수명 주기 알림 이벤트를 지원합니다. 현재 모든 유형의 Microsoft Graph API 리소스는 다음 조건 중 하나가 발생할 때 전송되는 microsoft.graph.subscriptionReauthorizationRequired를 지원합니다.

  • 액세스 토큰이 곧 만료됩니다.
  • Graph API 구독이 곧 만료됩니다.
  • 테넌트 관리자가 리소스를 읽을 수 있는 앱의 권한을 취소했습니다.

Graph API 구독이 만료된 후 갱신하지 않은 경우 새 Graph API 구독을 만들어야 합니다. 구독이 만료된 지 30일 이내인 경우 만료된 구독에 사용한 것과 동일한 파트너 토픽을 참조할 수 있습니다. Graph API 구독이 만료된 지 30일이 지난 경우 기존 파트너 토픽을 다시 사용할 수 없습니다. 이 경우 다른 파트너 토픽 이름을 지정해야 합니다. 또는 기존 파트너 토픽을 삭제하여 Graph API 구독을 만드는 동안 동일한 이름으로 새 파트너 토픽을 만들 수 있습니다.

Microsoft Graph API 구독을 갱신하는 방법

microsoft.graph.subscriptionReauthorizationRequired 이벤트를 받으면 애플리케이션은 다음 작업을 수행하여 Graph API 구독을 갱신해야 합니다.

  1. Graph API 구독을 만들 때 clientState 속성에 클라이언트 암호를 제공한 경우 해당 클라이언트 암호가 이벤트에 포함됩니다. 이벤트의 clientState가 Graph API 구독을 만들 때 사용된 값과 일치하는지 확인합니다.

  2. 앱에 다음 단계를 수행하는 유효한 액세스 토큰이 있는지 확인합니다. 자세한 정보는 자세한 지침이 포함된 샘플 섹션에서 제공됩니다.

  3. 다음 두 API 중 하나를 호출합니다. API 호출이 성공하면 변경 알림 흐름이 다시 시작됩니다.

    • 만료 날짜를 연장하지 않고 구독을 다시 인증하려면 /reauthorize 작업을 호출합니다.

      POST  https://graph.microsoft.com/beta/subscriptions/{id}/reauthorize

    • 정기적인 "갱신" 작업을 수행하여 다시 인증하고 동시에 구독을 갱신합니다.

      PATCH https://graph.microsoft.com/beta/subscriptions/{id}
Content-Type: application/json

{
   "expirationDateTime": "2024-04-30T11:00:00.0000000Z"
}

      앱이 더 이상 리소스에 액세스할 수 있는 권한이 없으면 갱신이 실패할 수 있습니다. 그런 다음, 앱이 구독을 성공적으로 다시 인증하기 위해 새 액세스 토큰을 가져와야 할 수도 있습니다.

권한 부여 문제는 만료되기 전에 구독을 갱신해야 하는 필요성을 대체하지 않습니다. 액세스 토큰의 수명 주기와 구독 만료는 동일하지 않습니다. 액세스 토큰은 구독 전에 만료할 수 있습니다. 액세스 토큰을 새로 고치기 위해 엔드포인트를 정기적으로 다시 인증하도록 준비하는 것이 중요합니다. 엔드포인트를 다시 인증해도 구독은 갱신되지 않습니다. 그러나 구독을 갱신하면 엔드포인트도 다시 인증됩니다.

Graph API 구독을 갱신 및/또는 다시 인증하는 경우 구독을 만들 때 지정한 것과 동일한 파트너 토픽이 사용됩니다.

새 expirationDateTime을 지정하는 경우 현재 시간으로부터 3시간 이상이어야 합니다. 그렇지 않으면 애플리케이션이 갱신 직후에 microsoft.graph.subscriptionReauthorizationRequired 이벤트를 받을 수 있습니다.

지원되는 언어를 사용하여 Graph API 구독을 다시 인증하는 방법에 대한 예제는 구독 재인증 요청을 참조하세요.

지원되는 언어를 사용하여 Graph API 구독을 갱신하고 다시 인증하는 방법에 대한 예제는 업데이트 구독 요청을 참조하세요.

자세한 지침이 포함된 샘플

Microsoft Graph API 설명서는 다음 지침이 포함된 코드 샘플을 제공합니다.

  • 사용하는 언어에 따라 특정 지침으로 개발 환경을 설정합니다. 지침에는 개발 목적으로 Microsoft 365 테넌트를 가져오는 방법도 포함됩니다.
  • Graph API 구독을 만듭니다. 구독을 갱신하려면 위의 Graph API 구독을 갱신하는 방법의 코드 조각을 사용하여 Graph API를 호출하면 됩니다.
  • Microsoft Graph API를 호출할 때 사용할 인증 토큰을 가져옵니다.

참고 항목

Microsoft Graph API Explorer를 사용하여 Graph API 구독을 만들 수 있습니다. 인증 및 이벤트 수신과 같은 솔루션의 다른 중요한 측면에는 계속해서 샘플을 사용해야 합니다.

웹 애플리케이션 샘플은 다음 언어에 사용할 수 있습니다.

  • C# 샘플. Graph API 구독을 만들고 갱신하는 방법을 포함하고 이벤트 흐름을 사용하도록 설정하는 몇 가지 단계를 안내하는 최신 샘플입니다.
  • Java 샘플
    • GraphAPIController에는 Graph API 구독을 만들고, 삭제하고, 갱신하는 샘플 코드가 포함되어 있습니다. 위의 Java 샘플 애플리케이션과 함께 사용해야 합니다.
  • NodeJS 샘플.

Important

Graph API 구독 생성의 일환으로 만들어진 파트너 토픽을 활성화해야 합니다. 또한 이벤트를 수신하려면 웹 애플리케이션에 대한 Event Grid 이벤트 구독을 만들어야 합니다. 이를 위해 웹 애플리케이션에 구성된 URL을 사용하여 이벤트 구독에서 이벤트를 웹후크 엔드포인트로 받습니다. 자세한 내용은 다음 단계를 참조하세요.

Important

다른 언어에 대한 샘플 코드가 필요하거나 질문이 있나요? ask-graph-and-grid@microsoft.com으로 메일을 보내세요.

다음 단계

다음 두 단계의 지침에 따라 Event Grid를 사용하여 Microsoft Graph API 이벤트를 수신하도록 설정을 완료합니다.

기타 유용한 링크: