오류 코드 및 오류 처리 | Graph API concepts(Graph API 개념)

적용 대상: Graph API | Azure Active Directory

Azure AD(Active Directory) Graph API를 사용하는 클라이언트 응용 프로그램은 다양한 조건에 가능한 한 매끄럽게 대응하고 고객에게 최상의 환경을 제공하기 위해 오류 처리 논리를 구현해야 합니다. 이 항목에서는 Azure AD Graph API에서 반환하고 처리 방법에 대한 일반 지침을 제공하는 오류 유형을 설명합니다.

Graph API 오류 처리

오류 유형

Graph API 오류는 다음 범주에서 발생합니다.

• 클라이언트 오류. 클라이언트 오류는 400 시리즈 HTTP 상태 코드로 표시됩니다. 잘못된 값을 가진 개체, 필수 속성 또는 속성 값이 누락된 개체, 존재하지 않는 리소스 액세스 시도, 읽기 전용 속성 업데이트 시도, 필수 인증 토큰 생략 등이 포함됩니다. 이러한 오류를 해결하려면 요청을 재시도하기 전에 기본 문제를 해결하십시오.
• 서버 오류. 서버 오류는 일시적인 디렉터리 실패 등 500 시리즈 HTTP 상태 코드로 표시됩니다. 이러한 오류는 대부분 일시적이며 요청을 재시도하면 해결할 수 있습니다.
• 네트워크/프로토콜 오류. 요청을 보내거나 응답을 받는 동안 호스트 이름 확인 오류, 중간에 닫힌 연결, SSL 협상 오류 등의 다양한 네트워크 관련 오류가 발생할 수 있습니다. 이러한 오류는 대부분 재시도하여 해결할 수 없습니다. 기본 문제를 해결해야 합니다. 그러나 호스트 이름 확인 실패, 시간 초과 등의 일부 오류는 요청을 재시도하여 해결할 수 있습니다.

오류 메시지 구조

Graph API 오류에는 HTTP 상태 코드, 메시지 및 값으로 구성된 특정 형식의 본문이 있습니다. 오류 처리 논리에서 오류 본문의 속성을 사용합니다.

참고: 일부 HTTP 응답에는 요청이 프록시 및 게이트웨이 서비스를 통해 라우팅되어 코드/메시지/값 응답 본문이 포함되어 있지 않을 수도 있습니다. HTTP 상태 코드만 기준으로 오류를 처리할 수 있는 기본 논리를 포함해야 합니다.

다음은 HTTP 400 Request_BadRequest 오류의 예입니다.

 HTTP/1.1 400 Bad Request
 Content-Type: application/json;odata=minimalmetadata;charset=utf-8
 request-id: ddca4a7e-02b1-4899-ace1-19860901f2fc
 Date: Tue, 02 Jul 2013 01:48:19 GMT
 …
 
 {
     "odata.error" : {
         "code" : "Request_BadRequest",
         "message" : {
             "lang" : "en",
             "value" : "A value is required for property 'mailNickname' of resource 'Group'."
         },
     "values" : null
    }
 }

각 메시지 본문에는 코드, 메시지 및 값 속성이 있습니다.

• 코드: 코드를 기준으로 분기되도록 오류 처리 논리를 디자인합니다.

  "code" : "Request_BadRequest"
  

• 메시지: 사람이 읽을 수 있는 오류 메시지를 나타내는 언어/값 튜플입니다. 콘텐츠는 값 필드에 있습니다. 다음 예에서는 mailNickname 속성 값이 누락되어 요청이 실패합니다.

  "message" : {
       "lang" : "en",
       "value" : "A value is required for property 'mailNickname' of resource 'Group'."
  }
  

• 값: 실패 특성에 대한 자세한 정보를 제공하는 이름/값 쌍의 컬렉션입니다. 다음 예에서는 값이 포함되어 있지 않습니다.

  "values" : null
  

오류 코드 참조

HTTP 오류 코드

다음 표에서는 Graph API 오류 코드, 오류 메시지 및 오류 수정 시 고려할 작업을 보여 줍니다.

가급적 긴 시간 간격 동안 분포("백오프 간격으로 다시 시도")되면서 무작위 분포 요소가 포함된 다시 시도에 응답하는 오류는 일반적으로 HTTP 500 시리즈 오류입니다. 400 시리즈 오류는 다시 시도하기 전에 수정해야 할 문제를 나타냅니다.

추가 리소스

• Azure AD Graph API 참조