Postman을 사용하여 Azure Digital Twins API에 요청을 보내는 방법

  • 아티클

Postman 은 데스크톱과 플러그인 기반 GUI에서 주요 HTTP 요청 기능을 제공하는 REST 테스트 도구입니다. 이를 사용하여 HTTP 요청을 만들고 Azure Digital Twins REST API에 제출할 수 있습니다. 이 문서에서는 Postman REST 클라이언트를 구성하여 Azure Digital Twins API와 상호 작용하는 방법을 설명합니다. 이 정보는 Azure Digital Twins 서비스에만 적용됩니다.

이 문서에는 다음 단계에 대한 정보가 포함되어 있습니다.

  1. Azure CLI를 사용하여 Postman에서 API 요청을 수행하는 데 사용할 전달자 토큰을 가져옵니다.
  2. Postman 컬렉션을 설정하고 POSTMAN REST 클라이언트를 구성하여 전달자 토큰을 사용해 인증합니다. 컬렉션을 설정할 때 다음 옵션 중 하나를 선택할 수 있습니다.
    1. 미리 빌드된 Azure Digital Twins API 요청 컬렉션을 가져옵니다.
    2. 자체 컬렉션을 처음부터 만듭니다.
  3. 구성된 컬렉션에 요청을 추가하고 이를 Azure Digital Twins API로 보냅니다.

Azure Digital Twins에는 사용할 수 있는 두 가지 API 집합(데이터 평면 및 컨트롤 플레인)이 있습니다. 이러한 API 집합 간의 차이점에 대한 자세한 내용은 Azure Digital Twins API 및 SDK를 참조하세요. 이 문서에는 두 API 집합에 대한 정보가 모두 포함되어 있습니다.

필수 조건

Postman을 사용하여 Azure Digital Twins API에 액세스하는 작업을 계속하려면 Azure Digital Twins 인스턴스를 설정하고 Postman을 다운로드해야 합니다. 이 섹션의 나머지 부분에서는 이러한 단계를 안내합니다.

Azure Digital Twins 인스턴스 설정

이 문서에서 Azure Digital Twins로 작업하려면 Azure Digital Twins 인스턴스와 이를 사용하는 데 필요한 권한이 필요합니다. 이미 Azure Digital Twins 인스턴스를 설정한 경우 해당 인스턴스를 사용하고 다음 섹션으로 건너뛸 수 있습니다. 그렇지 않으면 인스턴스 및 인증 설정의 지침을 따릅니다. 지침에는 각 단계를 성공적으로 완료했는지 확인하는 데 도움이 되는 정보가 포함되어 있습니다.

인스턴스가 설정되면 인스턴스의 호스트 이름을 적어 둡니다. Azure Portal에서 호스트 이름을 찾을 수 있습니다.

Postman 다운로드

다음으로, Postman 클라이언트의 데스크톱 버전을 다운로드합니다.

전달자 토큰 가져오기

이제 Postman과 Azure Digital Twins 인스턴스를 설정했으므로 Postman 요청이 Azure Digital Twins API에 대한 권한을 부여하는 데 사용할 수 있는 전달자 토큰을 가져와야 합니다.

이 토큰을 얻을 수 있는 몇 가지 방법이 있습니다. 이 문서에서는 Azure CLI를 사용하여 Azure 계정에 로그인하고 토큰을 가져옵니다.

Azure CLI를 로컬로 설치한 경우 머신에서 명령 프롬프트를 시작하여 다음 명령을 실행할 수 있습니다. 아니면 브라우저에서 Azure Cloud Shell 창을 열고 여기에서 명령을 실행할 수 있습니다.

  1. 먼저, 다음 명령을 실행하여 적절한 자격 증명을 사용하여 Azure에 로그인했는지 확인합니다.

    az login

  2. 다음으로, az account get-access-token 명령을 사용하여 Azure Digital twins 서비스에 대한 액세스 권한이 있는 전달자 토큰을 가져옵니다. 이 명령에서는 Azure Digital Twins 리소스에 액세스할 수 있는 액세스 토큰을 가져오기 위해 Azure Digital Twins 서비스 엔드포인트에 대한 리소스 ID를 전달합니다.

    토큰에 필요한 컨텍스트는 사용 중인 API 집합에 따라 달라지므로 아래 탭을 사용하여 데이터 평면 및 컨트롤 플레인 API 중에서 선택할 수 있습니다.

    데이터 평면 API에서 사용할 토큰을 가져오려면 토큰 컨텍스트에 대해 다음 정적 값을 사용합니다. 0b07f429-9f4b-4714-9392-cc5e8e80c8b0 이 값은 Azure Digital Twins 서비스 엔드포인트에 대한 리소스 ID입니다.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    참고 항목

    인스턴스와 다른 Microsoft Entra 테넌트에 속한 사용자 계정 또는 서비스 주체를 사용하여 Azure Digital Twins 인스턴스에 액세스해야 하는 경우 Azure Digital Twins 인스턴스의 "home" 테넌트에서 토큰을 요청해야 합니다. 이 프로세스에 대한 자세한 내용은 앱 인증 코드 작성을 참조하세요.

  3. 결과에서 accessToken 값을 복사하고 다음 섹션에서 사용할 수 있도록 저장합니다. 이 값은 요청에 권한을 부여하기 위해 Postman에 제공할 토큰 값입니다.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

팁

이 토큰은 5분 이상, 최대 60분 동안 유효합니다. 현재 토큰에 대해 할당된 시간을 초과하는 경우 이 섹션의 단계를 반복하여 새 토큰을 가져올 수 있습니다.

다음으로, 이 토큰을 사용하여 Azure Digital Twins에 대한 API 요청을 만들도록 Postman을 설정합니다.

Postman 컬렉션 정보

Postman의 요청은 컬렉션(요청 그룹)에 저장됩니다. 요청을 그룹화하는 컬렉션을 만드는 경우 한 번에 여러 요청에 일반 설정을 적용할 수 있습니다. 일반적인 설정은 전체 컬렉션에 대해 이러한 세부 정보를 한 번만 구성하면 되므로 Azure Digital Twins API에 대해 둘 이상의 요청을 만들려는 경우 권한 부여를 상당히 간소화합니다.

Azure Digital Twins를 사용하여 작업하는 경우 미리 빌드된 모든 Azure Digital Twins 요청 컬렉션을 가져와 시작할 수 있습니다. API를 탐색하고 요청 예제를 사용하여 프로젝트를 신속하게 설정하려는 경우 이 컬렉션을 가져올 수 있습니다.

또는 고유한 빈 컬렉션을 만들고 필요한 API만 호출하는 개별 요청으로 채워서 처음부터 시작하도록 선택할 수도 있습니다.

다음 섹션에서 이 두 프로세스에 대해 설명합니다. 문서의 나머지 부분은 로컬 Postman 애플리케이션에서 발생하므로 이제 컴퓨터에서 Postman 애플리케이션을 엽니다.

Azure Digital Twins API의 컬렉션 가져오기

Postman에서 Azure Digital Twins를 시작하는 빠른 방법은 API에 대한 미리 빌드된 요청 컬렉션을 가져오는 것입니다. 아래 단계에 따라 샘플 요청 데이터를 포함하는 인기 있는 Azure Digital Twins 데이터 평면 API 요청의 컬렉션을 가져옵니다.

  1. 기본 Postman 창에서 가져오기 단추를 선택합니다. Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. 이어지는 가져오기 창에서 링크를 선택하고 URL https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json을 입력합니다. 그런 다음, 가져오기를 선택하여 확인합니다.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

이제 새로 가져온 컬렉션을 기본 Postman 보기의 컬렉션 탭에서 볼 수 있습니다.

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

팁

특정 버전의 Azure Digital Twins API(컨트롤 플레인 또는 데이터 평면 포함)에 대한 전체 API 호출 집합을 가져오려면 Swagger 파일을 컬렉션으로 가져올 수도 있습니다. 컨트롤 플레인 및 데이터 평면 API의 Swagger 파일에 대한 링크는 Azure Digital Twins API 및 SDK를 참조하세요.

다음으로, 다음 섹션을 계속 진행하여 권한 부여를 위해 컬렉션에 전달자 토큰을 추가하고 Azure Digital Twins 인스턴스에 연결합니다.

권한 부여 구성

다음으로, 작성한 컬렉션을 편집하여 몇 가지 액세스 상세 정보를 구성합니다. 작성한 컬렉션을 강조 표시하고 추가 작업 보기 아이콘을 선택하여 작업 옵션을 표시합니다. 편집을 선택합니다.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

권한 부여를 위해 컬렉션에 전달자 토큰을 추가하려면 다음 단계를 수행합니다. 컬렉션의 모든 API 요청에 사용하기 위해 전달자 토큰 가져오기 섹션에서 수집한 토큰 값을 사용합니다.

  1. 컬렉션에 대한 편집 대화 상자에서 권한 부여 탭에 있는지 확인합니다.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. 유형을 OAuth 2.0으로 설정하고 액세스 토큰 상자에 액세스 토큰을 붙여넣습니다. 데이터 평면 API와 컨트롤 플레인 API에 대한 토큰이 다르기 때문에 사용 중인 API 유형에 올바른 토큰을 사용해야 합니다. 저장을 선택합니다.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    팁

    Postman 클라우드에서 요청과 함께 토큰을 저장하고 잠재적으로 다른 사용자와 토큰을 공유하려는 경우 토큰 공유를 사용하도록 선택할 수 있습니다.

기타 구성

컬렉션과 함께 제공되는 일부 변수를 설정하여 컬렉션을 Azure Digital Twins 리소스에 쉽게 연결할 수 있습니다. 컬렉션의 많은 요청에 동일한 값(예: Azure Digital Twins 인스턴스의 호스트 이름)이 필요한 경우 컬렉션의 모든 요청에 적용되는 변수에 값을 저장할 수 있습니다. Azure Digital Twins 컬렉션은 컬렉션 수준에서 설정할 수 있는 미리 생성된 변수와 함께 제공됩니다.

  1. 컬렉션에 대한 편집 대화 상자에서 변수 탭으로 이동합니다.

  2. 다음 표를 사용하여 컬렉션에 있는 변수의 값을 설정합니다.

    변수 API 세트 설명
    digitaltwins-hostname 데이터 평면 Azure Digital Twins 인스턴스의 호스트 이름 포털에서 사용자 인스턴스에 대한 개요 페이지에서 이 값을 찾을 수 있습니다.
    subscriptionId 제어 평면 Azure 구독 ID.
    digitalTwinInstance 제어 평면 Azure Digital Twins 인스턴스의 이름.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. 컬렉션에 추가 변수가 있으면 해당 값도 입력하고 저장합니다.

  4. 저장을 선택합니다.

위의 단계를 완료하면 컬렉션 구성 작업이 완료됩니다. 원하는 경우 컬렉션의 편집 탭을 닫을 수 있습니다.

요청 살펴보기

다음으로, Azure Digital Twins API 컬렉션 내의 요청을 탐색합니다. 컬렉션을 확장하여 미리 만든 요청(작업 범주별로 정렬됨)을 볼 수 있습니다.

요청에 따라 인스턴스와 해당 데이터에 대한 다른 정보가 필요합니다. 특정 요청을 작성하는 데 필요한 모든 정보를 보려면 Azure Digital Twins REST API 참조 설명서에서 요청 세부 정보를 조회합니다.

다음 단계를 사용하여 Postman 컬렉션에서 요청 세부 정보를 편집할 수 있습니다.

  1. 목록에서 선택하여 편집 가능한 세부 정보를 가져옵니다.

  2. 샘플 컬렉션에서 대부분의 요청은 더 이상 변경하지 않고 실행되도록 미리 구성됩니다.

  3. 다음 스크린샷은 DigitalTwinModels 추가 API를 보여 줍니다. 본문 탭에서 추가할 새 모델을 정의하는 JSON 페이로드를 볼 수 있습니다.

  4. 매개 변수 탭에서 경로 변수 아래 나열되는 변수에 대한 값을 입력합니다.

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. 요청을 실행하려면 보내기 단추를 사용합니다.

개별 요청 추가 섹션에 설명된 프로세스를 사용하여 컬렉션에 사용자 고유의 요청을 추가할 수도 있습니다.

사용자 고유의 컬렉션 만들기

Azure Digital Twins API의 기존 컬렉션을 가져오는 대신 고유의 컬렉션을 처음부터 만들 수도 있습니다. 그런 다음 Azure Digital Twins REST API 참조 설명서를 사용하여 개별 요청으로 채울 수 있습니다.

Postman 컬렉션 만들기

  1. 컬렉션을 만들려면 기본 Postman 창에서 새로 만들기 단추를 선택합니다.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    컬렉션 유형을 선택합니다.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. 탭이 열립니다. 새 컬렉션의 세부 사항을 입력합니다. 컬렉션의 기본 이름(새 컬렉션) 옆에 있는 편집 아이콘을 선택하여 원하는 이름으로 바꿉니다.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

다음으로, 권한 부여를 위해 컬렉션에 전달자 토큰을 추가하려면 다음 섹션을 계속 진행합니다.

권한 부여 구성

권한 부여를 위해 컬렉션에 전달자 토큰을 추가하려면 다음 단계를 수행합니다. 컬렉션의 모든 API 요청에 사용하기 위해 전달자 토큰 가져오기 섹션에서 수집한 토큰 값을 사용합니다.

  1. 새 컬렉션에 대한 편집 대화 상자에서 권한 부여 탭으로 이동합니다.

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. 유형을 OAuth 2.0으로 설정하고 액세스 토큰 상자에 액세스 토큰을 붙여넣은 다음 저장을 선택합니다.

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

위의 단계를 완료하면 컬렉션 구성 작업이 완료됩니다. 원하는 경우 새 컬렉션의 편집 탭을 닫을 수 있습니다.

새 컬렉션을 기본 Postman 보기의 컬렉션 탭에서 볼 수 있습니다.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

개별 요청 추가

이제 컬렉션이 설정되었으므로 Azure Digital Twin API에 자체 요청을 추가할 수 있습니다.

  1. 요청을 만들려면 새로 만들기 단추를 다시 사용합니다.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    요청 유형을 선택합니다.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  2. 이 작업을 수행하면 요청 저장 창이 열립니다. 여기에서 요청에 대한 이름을 입력하고, 설명(선택 사항)을 제공하고, 포함되는 컬렉션을 선택할 수 있습니다. 세부 정보를 입력하고 이전에 만든 컬렉션에 요청을 저장합니다.

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

이제 컬렉션에서 요청을 확인하고 선택하여 편집 가능한 세부 정보를 가져올 수 있습니다.

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

요청 세부 정보 설정

Azure Digital Twins API 중 하나에 대한 Postman 요청을 만들려면 API URL과 필요한 세부 항목에 대한 정보가 필요합니다. Azure Digital Twins REST API 참조 설명서에서 이 정보를 찾을 수 있습니다.

예제 쿼리를 계속하기 위해 이 문서에서는 쿼리 Azure Digital Twins 쿼리 API를 사용하여 인스턴스의 모든 디지털 트윈을 쿼리합니다.

  1. 참조 설명서에서 요청 URL과 유형을 가져옵니다. 쿼리 API의 경우 이 값은 현재 POSThttps://digitaltwins-host-name/query?api-version=2020-10-31입니다.

  2. Postman에서 요청에 대한 유형을 설정하고 요청 URL을 입력하고 필요에 따라 URL에 자리 표시자를 입력합니다. 필수 구성 요소 섹션에서 인스턴스의 호스트 이름을 사용합니다.

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. 매개 변수 탭에서 요청에 대해 표시된 매개 변수가 참조 설명서에 설명된 매개 변수와 일치하는지 확인합니다. Postman에서 이 요청에 대해 이전 단계에서 요청 URL을 입력하면 api-version 매개 변수가 자동으로 채워집니다. 쿼리 API의 경우 이 매개 변수가 유일한 필수 매개 변수이므로 이 단계가 완료됩니다.

  4. 권한 부여 탭에서 유형을 상위 항목에서 인증 상속으로 설정합니다. 이는 이 요청은 전체 컬렉션에 대해 이전에 설정한 권한 부여를 사용함을 나타냅니다.

  5. 헤더 탭에서 요청에 대해 표시된 헤더가 참조 설명서에 설명된 헤더와 일치하는지 확인합니다. 이 요청의 경우 여러 헤더가 자동으로 채워집니다. 쿼리 API의 경우 헤더 옵션이 필요하지 않으므로 이 단계가 완료됩니다.

  6. 본문 탭에서 요청에 대해 표시된 본문이 참조 설명서에 설명된 요구 사항과 일치하는지 확인합니다. 쿼리 API의 경우 쿼리 텍스트를 제공하려면 JSON 본문이 필요합니다. 다음은 인스턴스의 모든 디지털 트윈을 쿼리하는 이 요청에 대한 예제 본문입니다.

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    Azure Digital Twins 쿼리를 작성하는 방법에 대한 자세한 내용은 트윈 그래프 쿼리를 참조하세요.

  7. 요청 유형에 필요할 수 있는 다른 필드에 대한 참조 설명서를 확인합니다. 쿼리 API의 경우 Postman 요청에서 모든 요구 사항이 충족되었으므로 이 단계가 완료됩니다.

  8. 보내기 단추를 사용하여 완료된 요청을 보냅니다. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

요청을 보낸 후 응답 세부 정보는 Postman 창의 요청 아래에 표시됩니다. 응답의 상태 코드 및 본문 텍스트를 볼 수 있습니다.

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

참조 설명서에 제공된 예상 응답 데이터와 응답을 비교하여 결과를 확인하거나 발생한 오류에 대해 자세히 알아볼 수도 있습니다.

다음 단계

Digital Twins API에 대한 자세한 내용은 Azure Digital Twins API 및 SDK 또는 REST API에 대한 참조 설명서를 참조하세요.