.. _restapiserver: 

REST API Server
=======================

Genian ZTNA는 REST API Server를 사용자 및 조직 정보의 소스로 사용할 수 있습니다.

REST API Server 동기화를 통해 사용자 계정을 로컬에서 생성하여 관리 또는 정책에 사용 할 수 있습니다.

REST API Server 요청은 HTTP GET 방식을 사용하여 호출하며, 응답데이터형식은 JSON Object 형식이어야 합니다. 

slack 에서 사용자정보는 users.list API를 통해서 가져올 수 있습니다. Method URL 은 https://slack.com/api/users.list 이며 요청은 GET 과 POST 방식을 지원합니다.

ZTNA 에서 REST API 정보는 Swagger를 통해 제공합니다. :ref:`참고 - API 활용도구 제공: Swagger <rest-api-guide-swagger>`

REST API 의 상세 내용은 :ref:`API 가이드 <api>` 를 통해 확인할 수 있습니다. 



접속 테스트 하기
----------------------

접속 테스트를 수행하기 위해서는 다음에 기본값이 입력되어야 합니다.

+--------------------+---------------------------------+--------------------------------------------------------+
|    항목            |             설정값              |                         설명                           |
+====================+=================================+========================================================+
| REST API Server    | 서버주소                        | REST API를 호출할 서버 IP를 입력합니다.                |
+                    +---------------------------------+--------------------------------------------------------+
|                    | 페이지 파라미터 이름            | 다수의 출력값을 처리할 페이지 파라미터 이름을          |
+                    +                                 +--------------------------------------------------------+
|                    |                                 | 설정합니다.                                            |
+                    +---------------------------------+--------------------------------------------------------+
|                    | 페이지 시작번호                 | 페이지 시작번호를 설정합니다.                          |
+                    +---------------------------------+--------------------------------------------------------+
|                    | 페이지 사이즈 파라미터 이름     | 한 페이지에 출력할 갯수를 지정하는 파라미터 이름을     |
+                    +                                 +--------------------------------------------------------+
|                    |                                 | 설정합니다.                                            |
+                    +---------------------------------+--------------------------------------------------------+
|                    | 페이지 사이즈                   | 한 페이지에 출력할 갯수를 설정합니다.                  |
+                    +---------------------------------+--------------------------------------------------------+
|                    | 데이터소스 구분값               | 다수의 동기화 서버 사용 시 설정합니다.                 |
+--------------------+---------------------------------+--------------------------------------------------------+



.. note:: 접속 테스트가 정상적으로 되지 않을 경우 **정책서버** 와 **동기화 서버** 간 정상적인 통신 여부를 우선적으로 확인하시기 바랍니다.

동기화 설정하기
------------------------

#. 상단 항목의 **설정** 으로 이동합니다.
#. 왼쪽 설정 항목에서 **사용자인증 > 정보 동기화** 로 이동합니다.
#. **작업선택 > 생성** 을 클릭합니다.

**기본설정** 옵션

#. **ID** :  고유의 이름을 입력합니다.
#. **동기화 수행주기** : 동기화에 대해 지정된 시간 또는주기적인 간격을 선택합니다.
#. **정책적용여부** : 동기화 후 변경사항 반영을 위해 ``적용함`` 을 선택합니다 . 동기화 설정이 여러 개인 경우 ``적용안함`` 으로 설정하고 마지막 동기화만 사용하도록 설정 할 수 있습니다.

**데이터베이스** 옵션

* DB타입은 REST API Server 를 선택하고, 사용하고 있는 서버주소를 입력합니다.

    * 예) slack의 경우 https://slack.com, ZTNA의 경우 https://(정책서버IP):8443
* 페이징은 지원하지 않으므로 페이징관련 설정은 입력하지 않습니다.

#. **DB타입** : ``REST API Server``
#. **서버주소** : REST API Server의 주소를 입력합니다.
#. **페이지 파라미터이름** : 서버측 페이징을 통해서 정보를 가져오는 경우 페이지번호를 의미하는 파라미터 이름을 입력합니다.
#. **페이지 시작번호**: 서버측 페이징을 통해서 정보를 가져오는 경우 페이지 시작번호를 입력합니다.
#. **페이지사이즈 파라미터이름** : 서버측 페이징을 통해서 정보를 가져오는 경우 페이지당 가져오는 데이터수를 의미하는 파라미터 이름을 입력합니다.
#. **페이지사이즈** : 서버측 페이징을 통해서 정보를 가져오는 경우 페이지당 가져오는 데이터수를 입력합니다.
#. **데이터소스 구분값** : 데이터소스 구분값은 동기화 한 사용자 정보의 출처 식별을 위한 값입니다.

**사용자정보** 옵션

* 사용자정보출처를 입력할 때 상호인증을 API Key를 활용 한다면 /api/users.list?token=<API Token> 를 입력하거나, API 서비스 계정을 활용 한다면 /api/users.list 만 입력합니다. 자세한 내용은 :ref:`API 활용을 위한 상호 인증 방법 <rest-api-guide-auth>` 을 참고하시기 바랍니다.
* 컬럼명은 JSON Object에서 값을 추출하기 위한 경로를 입력합니다. 경로는 . 으로 구분합니다.
 
   * 예) JSON Response [ { "id": "..", "name": ".." }, { "id": "..",  "name": ".." } ] 인 경우에 ID컬럼명은 id, 이름컬럼명은 name 을 입력합니다.
   * 예) JSON Response { "users": { "members" : [ { "id": "..", "name": ".." }, { "id": "..",  "name": ".." } ] } } 인 경우에 ID컬럼명은 users.members.id, 이름컬럼명은 users.members.name 을 입력합니다.

#. **사용자정보출처** : 사용자정보동기화를 위한 URI 정보를 입력합니다. 입력된 URI설정은 서버주소 뒤에 경로명으로 추가됩니다.(예. /api/users.list 를 입력한 경우에 https://slack.com/api/users.list 를 호출합니다.) 
#. **사용자조건문** : 사용안함.
#. **사용자ID컬럼명** : JSON Object에서 사용자 ID 값의 경로를 입력합니다.(예. users.id)
#. **사용자이름컬럼명** : JSON Object에서 이름 값의 경로를 입력합니다.(예. users.name)
#. **부서ID컬럼명** : JSON Object에서 부서 ID 값의 경로를 입력합니다.(예. users.department_id)
#. 기타 추가 정보는 JSON Object에서 값의 경로를 입력합니다.

.. attention:: 그외 부서, 직급, 노드, 장비수명 정보 옵션 설정은 사용자정보 옵션과 동일한 방식으로 설정 사용할 수 있습니다.