REST를 사용하여 Microsoft Graph 쿼리

  • 3분

Microsoft Graph는 Microsoft 클라우드 서비스 리소스에 액세스할 수 있도록 하는 RESTful 웹 API입니다. 앱을 등록하고 사용자 또는 서비스에 대한 인증 토큰을 가져온 후 Microsoft Graph API에 대한 요청을 수행할 수 있습니다.

Microsoft Graph API는 microsoft.graph에서 OData 네임스페이스, 의 대부분의 리소스, 메서드 및 열거형을 정의합니다. 몇 개의 API 집합은 에서 callRecord와 같이 리소스를 정의하는 microsoft.graph.callRecords와 같은 하위 네임스페이스에 정의됩니다.

해당 항목에 명시적으로 지정되지 않은 경우 형식, 메서드 및 열거형이 microsoft.graph 네임스페이스의 일부인 것으로 가정합니다.

REST API 메서드 호출

사용자 또는 메일 메시지와 같은 리소스에서 읽거나 쓰려면 다음 샘플과 같은 요청을 생성합니다.

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

요청 구성 요소는 다음과 같습니다.

  • {HTTP method} - Microsoft Graph 요청에 사용된 HTTP 메서드입니다.
  • {version} - 애플리케이션에서 사용하는 Microsoft Graph API의 버전입니다.
  • {resource} - 참조하는 Microsoft Graph의 리소스입니다.
  • {query-parameters} - 응답을 사용자 지정하는 선택적 OData 쿼리 옵션 또는 REST 메서드 매개 변수입니다.

요청을 수행한 후 다음을 포함하는 응답이 반환됩니다.

  • 상태 코드 - 성공 또는 실패를 나타내는 HTTP 상태 코드입니다.
  • 응답 메시지 - 요청한 데이터 또는 작업의 결과입니다. 응답 메시지는 일부 작업에 대해 비어 있을 수 있습니다.
  • nextLink - 요청에서 많은 데이터를 반환하는 경우 @odata.nextLink에서 반환된 URL을 사용하여 페이지를 이동해야 합니다.

HTTP 메서드

Microsoft Graph는 요청에서 HTTP 메서드를 사용하여 요청을 수행하는 작업을 결정합니다. API는 다음 메서드를 지원합니다.

메서드 Description
GET 리소스에서 데이터를 읽습니다.
POST 새 리소스를 만들거나 작업을 수행합니다.
패치 새 값으로 리소스를 업데이트합니다.
PUT 리소스를 새 리소스로 바꿉니다.
Delete 리소스를 제거합니다.
  • CRUD 메서드 GET 및 DELETE의 경우 요청 본문은 필요하지 않습니다.
  • POST, PATCH, PUT 메서드는 추가 정보를 포함하는 요청 본문을 JSON 형식으로 지정해야 합니다. 예를 들어, 리소스의 속성 값입니다.

Version

Microsoft Graph는 현재 v1.0 및 beta의 두 가지 버전을 지원합니다.

  • v1.0은 일반 공급 API를 포함합니다. 모든 프로덕션 앱에 대해 v1.0 버전을 사용합니다.
  • beta는 현재 미리 보기로 제공되는 API를 포함합니다. 베타 API에 주요 변경 사항을 도입할 수 있으므로 개발 중인 앱을 테스트할 때만 베타 버전을 사용하는 것이 좋습니다. 프로덕션 앱에서 베타 API를 사용하지 마세요.

리소스

리소스는 일반적으로 속성으로 정의된 엔터티 또는 복합 형식일 수 있습니다. 엔터티는 항상 id 속성을 포함하여 복합 형식과 다릅니다.

URL에는 me, 사용자, 그룹, 드라이브, 사이트와 같이 요청에서 상호 작용하는 리소스가 포함됩니다. 종종 최상위 리소스는 또는 me/messages와 같은 기타 리소스에 액세스하는 데 사용할 수 있는 관계를 포함합니다. 메서드를 사용하여 리소스와 상호 작용할 수도 있습니다. 예를 들어 이메일을 보내려면 me/sendMail을 사용합니다.

각 리소스에 액세스하려면 다른 사용 권한이 필요할 수 있습니다. 리소스를 읽는 것보다 리소스를 만들거나 업데이트하려면 더 높은 수준의 사용 권한이 필요합니다. 필요한 권한에 대한 자세한 내용은 메서드 참조 항목을 참조하세요.

쿼리 매개 변수

쿼리 매개 변수는 OData 시스템 쿼리 옵션이거나 메서드에서 응답을 사용자 지정하는 데 사용할 수 있는 다른 문자열이 될 수 있습니다.

선택적 OData 시스템 쿼리 옵션을 사용하여 기본 응답보다 더 많거나 적은 속성을 포함할 수 있습니다. 사용자 지정 쿼리와 일치하는 항목에 대한 응답을 필터링하거나 메서드에 대한 다른 매개 변수를 제공할 수 있습니다.

예를 들어 다음 filter 매개 변수를 추가하면 emailAddress의 jon@contoso.com 속성으로 반환되는 메시지가 제한됩니다.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

다른 리소스

다음은 Microsoft Graph API를 사용하여 요청을 빌드 및 테스트하는 데 사용할 수 있는 일부 도구에 대한 링크입니다.