Postman 컬렉션을 사용하여 SAS REST API 실행

[#1]

Joe Furbee의 웨비나  Using SAS APIs를 통해 SAS REST API 작업 관련 Postman의 지대한 영향력에 큰 영감을 받았습니다. 이 포스팅에서는 Search for Tags(Annotations)를 위해 만든 Postman 컬렉션의 예제를 활용해 웨비나에서 다룬 내용을 자세히 다루고자 합니다.

SAS Viya에서는 태그를 사용하여 테이블, 열 및 기타 개체에 단순한 메타데이터 이상의 기타 정보를 추가할 수 있습니다. 사용자 인터페이스에서 이러한 태그는 데이터를 프로파일링할 때 자동으로 열에 추가되거나 수동으로 추가할 수 있습니다. 현재까지는 사용자 인터페이스에서 특정 태그가 있는 항목을 검색할 수 없습니다. 그러나 Annotations REST API를 사용한다면 가능합니다. Postman 기능을 활용한 SAS REST API 사용법에 대한 내용을 복습하는데 사용할 예제입니다.

Postman 컬렉션 작업

Postman은 REST API 작업에 유용한 도구입니다. 컬렉션을 통해 개별 요청을 그룹화 및 저장할 수 있습니다. 추가 구성을 위해 컬렉션 내에 폴더 생성도 가능합니다. 이 포스팅에서 다룰 예제 컬렉션은 다음과 같습니다.

크게 보시려면 이미지를 클릭하시기 바랍니다. 모바일 버전: 이미지를 보시려면 페이지 하단의 풀 버전을 선택하세요.

Postman 컬렉션을 작업할 때 다음 구성 요소가 필요합니다.

1. 환경 변수

환경 변수를 사용하여 Postman 요청을 보다 일반적이고 재사용 가능하도록 합니다. 환경에 따라 변수 값을 변경할 수 있습니다. SAS REST API 요청의 경우는 선택사항입니다.

이러한 변수는 사용될 위치에 따라 두 가지 방식으로 Postman에서 다뤄집니다. 요청 URL, 매개변수, 승인, 헤더 또는 본문 섹션에서 사용하는 경우 {{Environment_Variable_Name}} 을 사용합니다. 사전 요청 스크립트 또는 테스트 섹션의 경우 pm.environment.get("Environment_Variable_Name") 을 사용합니다.

요청

2. 요청 방법

요청의 HTTP 메소드를 선택합니다. SAS REST API에서 일반적으로 GET, POST 및 DELETE를 사용합니다. SAS REST API 요청에 필수입니다.

3. 요청 URL

 SAS REST API documentation를 기반으로 요청 URL을 입력합니다. SAS REST API 요청에 필수입니다.

4. 매개변수

경로 및 쿼리 매개변수를 보내는 데 사용합니다. 요청 URL에서 다음에 오는 항목입니다. 일반적으로 SAS REST API 요청에 선택사항입니다.

5. 승인

유형 승인을 선택하여 적절한 정보를 제공합니다. 대개 SAS REST API 요청에 필수이며 대부분의 SAS REST API 요청에 대해 Bearer 토큰 유형을 사용하고 Access 토큰을 제공합니다.

6. 헤더

요청 작업을 수행하는 데 필요한 추가 메타데이터를 제공합니다. 일반적으로 SAS REST API 요청에 필수입니다.

7. 바디

요청과 함께 보내야 하는 데이터를 입력합니다. 일반적으로 SAS REST API 요청에 필수입니다.

8. 사전 요청 스크립트

요청 실행 전 실행할 JavaScript 코드를 작성합니다. 이는 변수 값 설정과 같은 필요한 전처리를 수행하는 데 사용할 수 있습니다. SAS REST API 요청의 경우 선택사항입니다.

9. 테스트

요청이 실행된 후 실행할 JavaScript 코드를 작성합니다. 응답 데이터의 시각화와 같은 필요한 모든 후처리를 수행하는 데 사용할 수 있습니다. SAS REST API 요청의 경우 선택사항입니다.

응답

요청에 대한 Send 버튼을 클릭하면 요청에 대한 응답이 화면 하단에 표시됩니다.

10. 상태

요청에서 응답의 상태 코드를 반환합니다. 일반적으로 상태 코드 200은 OK(성공) 응답에 해당합니다. 특정 SAS REST API 요청에 대한 응답 코드는 해당 문서를 통해 확인하실 수 있습니다.

11. Pretty

이 모드는 더 쉽게 볼 수 있도록 응답 형식을 지정합니다.

12. Raw

이 모드에는 서식이 없는 응답 텍스트가 포함됩니다.

13. 미리보기

이 모드는 샌드박스 처리된 iframe에서 응답을 렌더링합니다.

14. 시각화

요청의 응답에 대해 코딩된 시각화를 볼 수 있습니다. 참고: 이러한 응답 시각화를 위해서 Postman 7.11 이상이 필요합니다. API 응답 시각화에 대한 자세한 내용은 Postman 문서를 통해 확인하실 수 있습니다.

이전에 Postman을 사용한 경험이 있는 경우, 대부분 친숙한 용어라 짐작됩니다. 만약 처음 사용하여 재사용이 가능한 Postman 요청 컬렉션을 구축하는 데 도움이 되는 구성 요소는 다음과 같습니다.

• 환경 변수
• 사전 요청 스크립트
• 테스트
• 시각화

태그 검색 포스트 컬렉션 예제

Search Tags Postman Collection은 다음 세 가지 요청으로 구성됩니다.

• Register_Client_ID_and_Get_Access_Token
• Search_Tags
• Delete_Client_ID

및 관련 환경 변수

환경 변수

이 컬렉션은 GEL_Shared-SearchTags 환경 변수를 사용합니다. 경우에 따라 환경 변수 설정을 확인 및 변경합니다.

시스템 변수

참고: 기본값은 GEL Viya 3.5 Shared Image RACE Collection에서 작동하도록 설정되어 있습니다.

• postman_version: 사용 중인 Postman의 버전 번호(예: 7.25.0). Postman 애플리케이션 메뉴에서 파일 > 설정 > 정보를 선택하여 확인할 수 있습니다
• client_id: 생성 중인 토큰을 식별하는 데 사용하는 값입니다. 참고: 다른 사람이 공유 이미지에서 데모를 실행 중인 경우 이 값을 변경해야 할 수 있습니다
• secret_word: 제공된 client_id의 비밀번호입니다
• viya_server_host: Viya 서버의 호스트 이름 또는 IP 주소 (예: sasviya01.race.sas.com)
• token: 관리자는 /opt/sas/viya/config/etc/SASSecurityCertificateFramework/tokens/consul/default/에 있는 client.token 파일에서 이 값을 가져올 수 있습니다.
• viya_username: SAS Viya에 액세스할 수 있는 사용자 이름
• viya_password: viya_username의 비밀번호

요청 변수

다른 태그 이름을 검색하려면 이 변수를 바꿉니다.

tag_name: 이 태그 이름을 가진 항목 검색

요청

이 Postman 컬렉션에는 특정 태그 이름이 있는 항목에 대한 검색을 수행하기 위한 일련의 요청이 포함되어 있습니다.

Register_Client_ID_and_Get_Access_Token

이 요청은 Client_ID를 등록하고 Viya 및 CAS REST API 호출에 대한 액세스 토큰을 얻기 위한 일련의 REST API 호출입니다. Viya 또는 CAS REST API 호출을 위해 필요합니다. 자세한 내용은 SAS REST APIs: Authentication & Authorization documentation.을 통해 확인하실 수 있습니다.

1. 사전 요청 스크립트 탭에서 액세스 토큰 가져오기를 수행하여 클라이언트 만들기를 수행합니다. access_token의 임시 환경 변수도 이 탭에서 설정합니다.
   
   
2. 클라이언트 만들기 요청을 기본 요청으로 수행합니다. 승인은 임시 저장된 환경 변수인 access_token을 Bearer 토큰 유형과 함께 사용합니다. 이 요청에 대해 적절한 헤더 및 바디도 설정합니다.
   

3. 테스트 탭에서 비밀번호를 사용하여 액세스 권한 부여를 수행합니다. 이 요청을 수행하려면 기본 인증을 위해 base-64로 인코딩된 client_id 및 secret_word가 전송되어야 하므로 이를 수행하여 해당값으로 my_encoded_cs의 환경 변수를 일시적으로 설정하는 데 사용되는 코드가 있습니다. 이 탭에서 access_token의 임시 환경 변수가 리셋됩니다. 이 값은 인증에 대한 후속 요청에서 사용됩니다. 또한 받은 응답 코드에 따라 Visualize 응답 탭의 텍스트를 설정하는 시각화 코드가 있습니다.
   

   다음은 Register_Client_ID_and_Get_Access_Token 요청을 실행한 Pretty 응답입니다.
   다음은 Register_Client_ID_and_Get_Access_Token 요청 실행의 Visualize 응답입니다.
   

Search_Tags

이 요청은 특정 태그 이름을 가진 항목을 검색하기 위한 일련의 REST API 호출입니다. 예제에서는 tag_name 환경 변수는 Individual로 설정되어 있습니다.

1. 사전 요청 스크립트 탭에서 태그 이름 요청에 대한 모든 주석 가져오기 필터링을 합니다. 임시 변수 annotation_id는 이 요청의 응답을 기반으로 설정됩니다. 제공된 tag_name이 존재하지 않으면 Visualize 응답 탭의 output_text가 '태그 이름이 존재하지 않음'으로 설정됩니다.
   
2. 주석 요청에 대한 구성원 개체 가져오기를 합니다. 참고: 요청은 지정된 태그 이름을 가진 모든 항목이 요청에 의해 반환되도록 하기 위해 매개변수에서 1000000 제한을 걸도록 설정되어 있습니다. 승인은 임시 저장된 환경 변수인 access_token을 Bearer 토큰 유형를 동시에 사용합니다. 이 요청에 대해 적절한 헤더 정보도 설정됩니다. 참고: 이 요청에는 바디 정보가 필요하지 않습니다.
   
3.  테스트 탭의 시각화 도우미 코드는 수신된 응답 코드를 기반으로 응답 시각화 탭의 텍스트를 설정합니다. 기본 요청에서 반환된 행이 없으면 Visualize 응답 탭의 output_text가 '제공된 태그 이름으로 태그가 지정된 항목 없음'으로 설정됩니다. 그렇지 않으면 제공된 tag_name이 있는 항목의 응답을 표시하도록 HTML 테이블이 작성됩니다.
   

   다음은 Search_Tags 요청을 실행한 Pretty 응답입니다.
   

   

   다음은 Search_Tags 요청을 실행한 Visualize 응답입니다.

   

Delete_Client_ID

이 요청은 Viya 및 CAS REST API 호출에 대해 설정된 Client_ID를 삭제하기 위한 일련의 REST API 호출입니다. 인증 및 권한 부여 프로세스를 정리하고 Client_ID를 나중에 다시 사용할 수 있게 합니다.

1. 사전 요청 스크립트 탭에서 클라이언트 자격 증명을 사용하여 액세스 권한 부여 요청을 합니다. 참고: 이는 클라이언트를 삭제할 수 있도록 적절한 자격 증명이 부여되었는지 확인하기 위한 임시 권한입니다. 새로운 임시 access_token 변수는 요청 응답에 따라 저장됩니다.
   
2. 클라이언트 삭제 요청을 수행합니다. 승인은 임시 저장된 환경 변수인 access_token을 Bearer 토큰 유형을 동시에 사용합니다. 참고: 이 요청에는 헤더 및 바디 정보가 필요하지 않습니다.
   
3. 테스트 탭의 시각화 도우미 코드는 수신된 응답 코드를 기반으로 응답 시각화 탭의 텍스트를 설정합니다. 참고: Delete Client 요청은 성공을 뜻하는 200 응답 대신 Client_ID를 찾을 수 없다는 상태를 나타내는 코드 404를 보여줍니다. 또한 환경 변수 access_token 및 my_encoded_cs가 삭제됩니다.

   다음은 Delete_Client_ID 요청을 실행한 pPretty 응답입니다. 참고: 404 Not Found는 Client_ID가 삭제되었거나 찾을 수 없는 경우 받게 되는 응답입니다.

   다음은 Delete_Client_ID 요청을 실행한 Visualize 응답입니다.
   

요약

결론적으로 Postman 컬렉션을 생성해 환경 변수, 사전 요청 및 테스트를 사용하는 것은 요청을 그룹화하고 서로 다른 환경에서도 빈번히 재사용할 수 있도록 만드는 효과적인 방법입니다.

Postman에 대한 자세한 내용은 해당 문서를 통해 확인하실 수 있습니다. SAS Viya REST API에 대한 자세한 내용은 해당 문서를 통해 확인하실 수 있습니다.

참고문헌

Joe Furbee의 웹 세미나: Using SAS APIs

• Postman documentation

감사 말씀

귀감이 되는  webinar를 제공해주신 Joe Furbee(@joeFurbee)님 Postman의 기능에 대해 자세한 설명 및 SAS REST API 사용법에 도움을 주셔서 감사합니다.