Azure Digital Twins Swagger 참조 설명서
중요
새 버전의 Azure Digital Twins 서비스가 릴리스되었습니다. 새 서비스의 확장된 기능에 비추어 원래 Azure Digital Twins 서비스(이 설명서 집합에 설명됨)가 사용 중지되었습니다.
새 서비스에 대한 설명서를 보려면 활성 Azure Digital Twins 설명서를 방문하세요.
프로비전된 Azure Digital Twins 인스턴스에는 각각 자동으로 생성된 고유한 Swagger 참조 설명서가 포함됩니다.
Swagger 또는 OpenAPI는 복잡한 API 정보를 대화형 및 언어 중립적 참조 리소스로 통합합니다. Swagger는 API에 대한 작업을 수행하는 데 사용할 JSON 페이로드, HTTP 메서드 및 특정 엔드포인트에 대한 중요 참고 자료를 제공합니다.
Swagger 요약
Swagger는 다음을 비롯한 API의 대화형 요약을 제공합니다.
- API 및 개체 모델 정보.
- 필수 요청 페이로드, 헤더, 매개 변수, 컨텍스트 경로 및 HTTP 메서드를 지정하는 REST API 엔드포인트.
- API 기능 테스트
- HTTP 응답의 유효성을 검사하고 확인하는 예제 응답 정보.
- 오류 코드 정보
Swagger는 Azure Digital Twins 관리 API에 대한 호출 테스트와 개발을 보조하는 편리한 도구입니다.
팁
Swagger 미리 보기는 API 기능 집합을 설명하기 위해 제공됩니다. docs.westcentralus.azuresmartspaces.net/management/swagger에서 호스팅됩니다.
다음에서 생성된 고유한 관리 API Swagger 설명서에 액세스할 수 있습니다.
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
| 이름 | 다음 항목으로 교체 |
|---|---|
| YOUR_INSTANCE_NAME | Azure Digital Twins 인스턴스의 이름 |
| YOUR_LOCATION | 인스턴스를 호스팅하는 서버 지역 |
참조 자료
자동으로 생성되는 Swagger 참조 자료는 중요한 개념에 대한 간단한 개요, 사용 가능한 관리 API 엔드포인트 및 개발과 테스트를 보조하는 각 개체 모델에 대한 설명을 제공합니다.
간결한 요약에서는 API를 설명합니다.
관리 API 개체 모델도 나열됩니다.
키 특성의 더 자세한 요약은 각 나열된 개체 모델을 선택하면 됩니다.
생성된 Swagger 개체 모델은 사용 가능한 모든 Azure Digital Twins 개체 및 API를 읽는 데 편리합니다. 개발자는 Azure Digital Twins에서 솔루션을 빌드할 때 이 리소스를 사용할 수 있습니다.
엔드포인트 요약
또한 Swagger는 관리 API를 구성하는 모든 엔드포인트에 대한 철저한 개요를 제공합니다.
나열된 각 엔드포인트에는 다음과 같은 필수 요청 정보도 포함됩니다.
- 필수 매개 변수
- 필수 매개 변수 데이터 형식
- 리소스에 액세스하는 HTTP 메서드.
각 리소스를 선택하여 추가 콘텐츠를 표시하여 더 자세한 개요를 확인합니다.
Swagger를 사용하여 엔드포인트 테스트
Swagger의 강력한 기능 중 하나는 문서 UI를 통해 직접 API 엔드포인트를 테스트할 수 있는 기능입니다.
특정 엔드포인트를 선택하면 시도 단추가 표시됩니다.
해당 섹션을 확장하면 각 필수 및 선택적 매개 변수에 대한 입력 필드가 표시됩니다. 올바른 값을 입력하고 실행을 선택합니다.
테스트를 실행한 후 응답 데이터의 유효성을 검사할 수 있습니다.
Swagger 응답 데이터
나열된 각 엔드포인트에는 개발 및 테스트의 유효성을 검사하는 응답 본문 데이터도 포함됩니다. 이러한 예제에는 성공적인 HTTP 요청에 대한 상태 코드 및 JSON이 포함됩니다.
예제에는 실패한 테스트를 디버그하거나 개선하는 오류 코드도 포함됩니다.
Swagger OAuth 2.0 권한 부여
참고
- Azure Digital Twins 리소스를 만든 사용자 주체에는 공간 관리자 역할 할당이 있으며 다른 사용자에 대한 추가 역할 할당을 만들 수 있습니다. 이러한 사용자와 해당 역할은 API를 호출할 수 있는 권한을 부여받을 수 있습니다.
빠른 시작의 단계에 따라 Azure Active Directory 애플리케이션을 만들고 구성합니다. 또는 기존 앱 등록을 다시 사용할 수 있습니다.
Azure Active Directory 앱 등록에 다음 리디렉션 URI 를 추가합니다.
https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html이름 다음 항목으로 교체 예제 YOUR_SWAGGER_URL 포털에 있는 관리 REST API 설명서 URL https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swaggerOAuth 2.0 암시적 권한 부여> 흐름을 사용할 수 있도록 하려면 암시적액세스 토큰 부여 확인란을 선택합니다. 구성을 선택한 다음 저장을 선택합니다.
Azure Active Directory 앱의 클라이언트 ID 를 복사합니다.
Azure Active Directory 등록을 완료한 후:
swagger 페이지에서 권한 부여 단추를 선택합니다.
애플리케이션 ID를 client_id 필드에 붙여넣습니다.
그러면 다음과 같은 성공 모달로 리디렉션됩니다.
OAuth 2.0으로 보호되는 대화형 테스트 요청에 대한 자세한 내용은 공식 설명서를 참조하세요.
다음 단계
Azure Digital Twins 개체 모델 및 공간 인텔리전스 그래프에 대해 자세히 알아보려면 Azure Digital Twins 개체 모델 이해를 읽어보세요.
관리 API를 사용하여 인증하는 방법을 알아보려면 API를 사용하여 인증을 읽어보세요.