가상 폴더

가상 폴더는 여러 다른 세션에서 공유되며, 지속적이고, 재사용 가능한 파일을 제공합니다.

새로운 세션을 생성할 때 가상 폴더를 마운트할 수 있으며, 로컬 파일 시스템의 일반 디렉토리처럼 사용할 수 있습니다. 물론, 가상 폴더의 내용에 대한 읽기/쓰기는 내부적으로 네트워크 파일 시스템을 사용하기 때문에, 주요 스크래치 디렉토리(대부분의 커널에서는 /home/work)에 비해 성능이 저하될 수 있습니다.

또한, 가상 폴더를 다른 사용자와 공유할 수 있으며, 적절한 권한을 부여하여 초대할 수 있습니다. 현재, 권한은 각각 세 가지 레벨로 구분됩니다: 읽기 전용, 읽기-쓰기, 읽기-쓰기-삭제. 이들은 각각 'ro' , 'rw', 'wd' 라는 짧은 문자열로 표현됩니다. 가상 폴더의 소유자는 폴더에 대해 읽기-쓰기-삭제 권한을 가집니다.

가상 폴더 목록

현재 키페어로 생성된 가상 폴더의 목록을 반환합니다.

URI: /folders
메소드 : GET

매개변수

매개변수	타입	설명
`all`	`bool`	(선택 사항) 매개 변수가 `True` 인 경우, 현재 사용자가 속하지 않는 폴더를 포함한 모든 가상 폴더를 반환합니다. 최고 관리자만이 해당 매개변수(기본값: `False`)를 사용할 수 있습니다.
`group_id`	`UUID \| str`	(선택 사항) 매개 변수가 설정되면, 지정된 그룹에 속한 가상 폴더를 반환합니다. 사용자 유형 가상 폴더에는 영향을 미치지 않습니다.

응답

HTTP 상태 코드	설명
200 OK	Success

필드	타입	값
(root)	`list[object]`	A list of Virtual Folder List Item Object

예시:

[
   {
      "name": "myfolder",
      "id": "b4b1b16c-d07f-4f1f-b60e-da9449aa60a6",
      "host": "local:volume1",
      "usage_mode": "general",
      "created_at": "2020-11-28 13:30:30.912056+00",
      "is_owner": "true",
      "permission": "rw",
      "user": "dfa9da54-4b28-432f-be29-c0d680c7a412",
      "group": null,
      "creator": "admin@lablup.com",
      "user_email": "admin@lablup.com",
      "group_name": null,
      "ownership_type": "user",
      "unmanaged_path": null,
      "cloneable": "false",
   }
]

가상 폴더 호스트 목록

새로운 가상 폴더를 만들 수 있는 현재 키페어의 호스트 이름 목록을 반환합니다.

Added in version v4.20190315.

URI: /folders/_/hosts
메소드 : GET

매개변수

None

응답

HTTP 상태 코드	설명
200 OK	Success

필드	타입	값
`default`	`str`	The default virtual folder host
`allowed`	`list[str]`	The list of available virtual folder hosts

예시:

{
  "default": "seoul:nfs1",
  "allowed": ["seoul:nfs1", "seoul:nfs2", "seoul:cephfs1"]
}

가상 폴더 생성

URI: /folders
Method: POST

현재 API 키와 연결된 가상 폴더를 생성합니다.

매개변수

매개변수	타입	설명
`name`	`str`	The human-readable name of the virtual folder
`host`	`str`	(optional) The name of the virtual folder host
`usage_mode`	`str`	(선택 사항) 가상 폴더의 목적. 가능한 값은 `general`, `model`, `data` (기본값: `general`) 입니다.
`permission`	`str`	(선택 사항) 가상 폴더의 기본 공유 권한. 가상 폴더의 소유자는 해당 매개 변수와 관계없이 항상 `wd` 권한을 가집니다. 가능한 값은 `ro`, `rw`, `wd` (기본값: `rw`) 입니다.
`group_id`	`UUID \| str`	(선택 사항) 해당 매개 변수가 설정되면 그룹 유형의 가상 폴더가 생성됩니다. 만약 비어 있다면, 사용자 유형의 가상 폴더가 생성됩니다.
`quota`	`int`	(선택 사항) 가상 폴더의 쿼터를 바이트 단위로 설정합니다. 하지만 쿼터는 xfs 파일 시스템에서만 지원됩니다. 디렉토리 단위 쿼터를 지원하지 않는 다른 파일 시스템에서는 해당 매개 변수가 무시됩니다.

예시:

{
  "name": "My Data",
  "host": "seoul:nfs1"
}

응답

HTTP 상태 코드	설명
201 Created	커널이 성공적으로 생성되었습니다.
400 Bad Request	잘못되었거나 이미 존재하는 가상 폴더와 중복되는 이름입니다.
406 Not acceptable	가상 폴더의 개수 제한을 초과했습니다. (예: 가질 수 있는 최대 폴더 개수)

필드	타입	값
`id`	`slug`	The unique folder ID used for later API calls
`name`	`str`	The human-readable name of the created virtual folder
`host`	`str`	The name of the virtual folder host where the new folder is created

예시:

{
  "id": "aef1691db3354020986d6498340df13c",
  "name": "My Data",
  "host": "nfs1",
  "usage_mode": "general",
  "permission": "rw",
  "creator": "admin@lablup.com",
  "ownership_type": "user",
  "user": "dfa9da54-4b28-432f-be29-c0d680c7a412",
  "group": "",
}

가상 폴더 정보 얻기

URI: /folders/:name
메소드 : GET

가상 폴더의 정보를 검색합니다. 성능상의 이유로, 반환된 정보는 실시간이 아닐 수 있습니다; 보통 서버측에서 몇 초마다 업데이트됩니다.

매개변수

매개변수	타입	설명
`name`	`str`	The human-readable name of the virtual folder

응답

HTTP 상태 코드	설명
200 OK	정보가 성공적으로 반환되었습니다.
404 Not Found	폴더가 없거나 폴더에 접근할 적절한 권한을 가지고 있지 않습니다.

필드	타입	값
(root)	`object`	Virtual Folder Item Object

가상 폴더 지우기

URI: /folders/:name
Method: DELETE

주어진 가상 폴더의 모든 내용을 즉시 삭제하고 미래의 마운트에 폴더를 사용할 수 없게 합니다.

위험

실행 중인 커널 중 삭제된 가상 폴더를 마운트한 커널이 있다면, 해당 커널은 오작동할 수 있습니다!

경고

이 API가 호출되면 내용을 되돌릴 수 있는 방법이 없습니다.

매개변수

매개변수	설명
`name`	The human-readable name of the virtual folder

응답

HTTP 상태 코드	설명
204 No Content	폴더가 성공적으로 삭제되었습니다.
404 Not Found	폴더가 없거나 폴더를 삭제할 적절한 권한을 가지고 있지 않습니다.

가상 폴더 이름 바꾸기

URI: /folders/:name/rename
Method: POST

현재 API 키와 연결된 가상 폴더의 이름을 바꿉니다.

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder
`new_name`	`str`	New virtual folder name

응답

HTTP 상태 코드	설명
201 Created	The folder is successfully renamed.
404 Not Found	폴더를 찾을 수 없거나 폴더 이름을 바꿀 적절한 권한을 가지고 있지 않습니다.

가상 폴더 내 파일 목록

현재 키페어와 연결된 가상 폴더 내 파일 목록을 반환합니다.

URI: /folders/:name/files
메소드 : GET

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder
`path`	`str`	Path inside the virtual folder (default: root)

응답

HTTP 상태 코드	설명
200 OK	Success.
404 Not Found	폴더에 접근할 수 없거나 경로를 찾을 수 없습니다.

필드	타입	값
`files`	`list[object]`	Virtual Folder File Object 목록

가상 폴더에 파일 업로드

현재 키페어와 연결된 가상 폴더에 로컬 파일을 업로드합니다. Manager는 내부적으로 Backend.AI Storage-Proxy 서비스에 업로드를 위임합니다. JSON 웹 토큰은 요청 인증에 사용됩니다.

URI: /folders/:name/request-upload
Method: POST

경고

가상 폴더 내 동일한 이름의 파일이 이미 존재하면 경고 없이 덮어써집니다.

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder
`path`	`str`	Path of the local file to upload
`size`	`int`	The total size of the local file to upload

응답

HTTP 상태 코드	설명
200 OK	Success.

필드	타입	값
`token`	`str`	Storage-Proxy 서비스에 업로드 세션 인증을 위한 JSON 웹 토큰
`url`	`str`	Storage-Proxy에 대한 요청 URL. 클라이언트는 이 URL을 사용하여 파일을 업로드해야 합니다.

가상 폴더 내에 새 디렉토리 생성하기

현재 키페어에 연결된 가상 폴더에 새 디렉토리를 생성합니다. 이 API는 존재하지 않는 상위 디렉토리를 재귀적으로 생성합니다.

URI: /folders/:name/mkdir
Method: POST

경고

가상 폴더 내 동일한 이름의 디렉토리가 이미 존재하면 경고 없이 덮어써질 수 있습니다.

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder.
`path`	`str`	The relative path of a new folder to create inside the virtual folder
`parents`	`bool`	`True` 일 경우, 지정한 상위 디렉토리가 존재하지 않으면 같이 생성합니다.
`exist_ok`	`bool`	디렉토리 이름이 이미 존재하면 오류 없이 덮어씁니다.

응답

HTTP 상태 코드	설명
201 Created	Success.
400 Bad Request	디렉토리가 아닌 동일한 이름의 파일이 이미 존재합니다.
404 Not Found	파일이 없거나 해당 폴더에 쓰기 권한이 없습니다.

가상 폴더에 있는 파일 또는 디렉토리 다운로드하기

현재 keypair에서 연결된 가상 폴더에 있는 파일 또는 디렉토리를 다운로드합니다. 내부적으로, Manager는 Backend.AI Storage-Proxy 서비스에 다운로드를 위임합니다. JSON 웹 토큰은 요청의 인증에 사용됩니다.

Added in version v4.20190315.

URI: /folders/:name/request-download
Method: POST

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder
`path`	`str`	다운로드를 위해 가상 폴더 내 파일 또는 디렉토리의 경로
`archive`	`bool`	해당 매개변수가 `True` 고 path``가 디렉토리일 경우, 디렉토리는 zip 파일로 압축됩니다 (기본값: ``False).

응답

HTTP 상태 코드	설명
200 OK	Success.
404 Not Found	파일을 찾을 수 없거나 해당 폴더에 접근할 수 있는 권한이 없습니다.

필드	타입	값
`token`	`str`	JSON 웹 토큰은 Storage-Proxy 서비스의 다운로드 세션 인증에 사용됩니다.
`url`	`str`	저장-프록시에 대한 요청 URL입니다. 클라이언트는 이 URL을 사용하여 파일을 다운로드해야 합니다.

가상 폴더 내 파일 삭제하기

가상 폴더 내 파일을 삭제합니다.

경고

한 번 API가 호출되면 파일을 되돌릴 수 없습니다.

URI: /folders/:name/delete-files
Method: DELETE

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder
`files`	`list[str]`	File paths inside the virtual folder to delete
`recursive`	`bool`	설정이 True로 되어 있으면 폴더를 재귀적으로 삭제합니다. 기본값은 False입니다.

응답

HTTP 상태 코드	설명
200 OK	Success.
400 Bad Request	recursive 옵션을 True로 설정하지 않고 폴더를 삭제하려고 했습니다.
404 Not Found	해당 폴더가 없거나 폴더 내 파일을 삭제할 수 있는 권한이 없습니다.

가상 폴더 내 파일 이름을 변경하기

Rename a file inside a virtual folder.

URI: /folders/:name/rename-file
Method: POST

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder
`target_path`	`str`	The relative path of target file or directory
`new_name`	`str`	The new name of the file or directory
`is_dir`	`bool`	Flag that indicates the `target_path` is a directory or not

응답

HTTP 상태 코드	설명
200 OK	Success.
400 Bad Request	is_dir 옵션을 True로 설정하지 않고 디렉토리 이름을 변경하려고 했습니다.
404 Not Found	해당 폴더가 없거나 폴더 내 파일을 이름을 변경할 수 있는 권한이 없습니다.

가상 폴더 내 초대 목록 보기

요청한 사용자가 받은 보류중인 초대 목록을 반환합니다. 이 목록 다른 사용자가 보낸 초대가 표시됩니다.

URI : /folders/invitations/list
메소드 : GET

매개변수

이 API는 파라미터가 필요하지 않습니다.

응답

HTTP 상태 코드	설명
200 OK	Success.

필드	타입	값
`invitations`	`list[object]`	A list of Virtual Folder Invitation Object

초대 생성하기

적절한 권한으로 가상 폴더를 공유할 다른 사용자를 초대합니다. 해당 사용자가 이미 초대되어 있다면 이 API는 새로운 초대를 생성하지 않거나 기존 초대 권한을 업데이트하지 않습니다.

URI : /folders/:name/invite
Method: POST

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder
`perm`	`str`	The permission to grant to invitee
`emails`	`list[slug]`	A list of user emails to invite

응답

HTTP 상태 코드	설명
200 OK	Success.
400 Bad Request	초대받을 사용자가 주어지지 않았습니다.
404 Not Found	초대가 없습니다.

필드	타입	값
`invited_ids`	`list[slug]`	A list of invited user emails

초대 수락하기

초대를 수락하고 초대에 따른 가상 폴더의 권한을 부여받습니다.

URI : /folders/invitations/accept
Method: POST

매개변수

매개변수	타입	설명
`inv_id`	`slug`	The unique invitation ID

응답

HTTP 상태 코드	설명
200 OK	Success.
400 Bad Request	대상 가상 폴더 이름이 이미 존재하는 가상 폴더 이름과 중복됩니다.
404 Not Found	존재하지 않는 초대입니다.

초대 거절하기

초대를 거절합니다.

URI : /folders/invitations/delete
Method: DELETE

매개변수

매개변수	타입	설명
`inv_id`	`slug`	The unique invitation ID

응답

HTTP 상태 코드	설명
200 OK	Success.
404 Not Found	존재하지 않는 초대입니다.

필드	타입	값
`msg`	`str`	Detail message for the invitation deletion

보낸 초대 목록

요청한 사용자가 보낸 가상 폴더 초대 목록을 반환합니다. 이미 수락하거나 거절한 초대는 포함되지 않습니다.

URI : /folders/invitations/list-sent
메소드 : GET

매개변수

이 API는 파라미터가 필요하지 않습니다.

응답

HTTP 상태 코드	설명
200 OK	Success.

필드	타입	값
`invitations`	`list[object]`	A list of Virtual Folder Invitation Object

초대 업데이트

이미 보냈지만 수락하거나 거절하지 않은 초대 권한을 업데이트합니다.

URI : /folders/invitations/update/:inv_id
Method: POST

매개변수

매개변수	타입	설명
`:inv_id`	`str`	The unique invitation ID
`perm`	`str`	The permission to grant to invitee

응답

HTTP 상태 코드	설명
200 OK	Success.
400 Bad Request	권한을 지정하지 않았습니다.
404 Not Found	초대가 없습니다.

필드	타입	값
`msg`	`str`	An update message string

공유받은 가상 폴더 나가기

공유받은 가상 폴더에서 나갑니다.

그룹 vfolder 또는 요청한 사용자가 소유한 vfolder는 나갈 수 없습니다.

URI : /folders/:name/leave
Method: POST

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder

응답

HTTP 상태 코드	설명
200 OK	Success.
404 Not Found	가상 폴더가 없습니다.

필드	타입	값
`msg`	`str`	A result message string

가상 폴더 공유 사용자 목록

요청자의 가상 폴더를 공유하는 사용자 목록을 반환합니다.

URI : /folders/_/shared
메소드 : GET

매개변수

매개변수	타입	설명
`vfolder_id`	`str`	(선택 사항) 공유된 사용자를 나열할 가상 폴더의 고유 ID입니다. 지정하지 않으면 요청자가 생성한 모든 가상 폴더를 공유하는 사용자를 나열합니다.

응답

HTTP 상태 코드	설명
200 OK	Success.

필드	타입	값
`shared`	`list[object]`	A list of information about shared users.

예시:

[
   {
      "vfolder_id": "aef1691db3354020986d6498340df13c",
      "vfolder_name": "My Data",
      "shared_by": "admin@lablup.com",
      "shared-to": {
         "uuid": "dfa9da54-4b28-432f-be29-c0d680c7a412",
         "email": "user@lablup.com"
      },
      "perm": "ro"
   }
]

공유된 가상 폴더의 권한 업데이트

공유된 가상 폴더의 사용자 권한을 업데이트합니다.

URI : /folders/_/shared
Method: POST

매개변수

매개변수	타입	설명
`vfolder`	`UUID`	The unique virtual folder ID
`user`	`UUID`	The unique user ID
`perm`	`str`	The permission to update for the `user` on `vfolder`

응답

HTTP 상태 코드	설명
200 OK	Success.
400 Bad Request	권한 또는 사용자가 지정되지 않았습니다.
404 Not Found	가상 폴더가 없습니다.

필드	타입	값
`msg`	`str`	An update message string

개별 사용자에게 그룹 가상 폴더 공유

권한을 덮어쓰는 사용자에게 그룹 가상 폴더를 공유합니다.

생성된 초대를 통해 vfolder_permission 관계를 직접 생성합니다. 그룹 가상 폴더만 직접 공유할 수 있습니다.

이 API는 그룹 가상 폴더를 읽기 전용 권한으로 모든 그룹 멤버에게 공유하고, 일부 사용자에게는 읽기/쓰기 권한을 부여하고 싶을 때 유용합니다.

안내: 이 API는 그룹 가상 폴더에만 사용할 수 있습니다.

URI: /folders/:name/share
Method: POST

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder
`permission`	`str`	Overriding permission to share the group virtual folder
`emails`	`list[str]`	A list of user emails to share

응답

HTTP 상태 코드	설명
201 Created	Success.
400 Bad Request	권한 혹은 이메일이 주어지지 않았습니다.
404 Not Found	가상 폴더가 없습니다.

필드	타입	값
`shared_emails`	`list[str]`	A list of user emails those are successfully shared the virtual folder

사용자로부터 그룹 가상 폴더 공유 해제

Unshare a group virtual folder from users

안내: 이 API는 그룹 가상 폴더에만 사용할 수 있습니다.

URI: /folders/:name/unshare
Method: DELETE

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder
`emails`	`list[str]`	A list of user emails to unshare

응답

HTTP 상태 코드	설명
200 OK	Success.
400 Bad Request	이메일이 주어지지 않았습니다.
404 Not Found	가상 폴더가 없습니다.

필드	타입	값
`unshared_emails`	`list[str]`	A list of user emails those are successfully unshared the virtual folder

가상 폴더 복제

Clone a virtual folder

URI: /folders/:name/clone
Method: POST

매개변수

매개변수	타입	설명
`:name`	`str`	The human-readable name of the virtual folder
`cloneable`	`bool`	``True``일 경우, 복제된 가상 폴더를 다시 복제할 수 있습니다.
`target_name`	`str`	The name of the new virtual folder
`target_host`	`str`	The targe host volume of the new virtual folder
`usage_mode`	`str`	(선택 사항) 새 가상 폴더의 목적. 허용되는 값은 `general`, `model`, `data` (기본값: `general`)입니다.
`permission`	`str`	(선택 사항) 새 가상 폴더의 기본 공유 권한. 가상 폴더의 소유자는 해당 매개변수와 무관하게 항상 `wd` 권한을 가집니다. 허용되는 값은 `ro`, `rw`, `wd` 입니다.

응답

HTTP 상태 코드	설명
200 OK	Success.
400 Bad Request	타겟 이름, 타겟 호스트, 권한이 없습니다.
403 Forbidden	소스 가상 폴더는 복제할 수 없습니다.
404 Not Found	가상 폴더가 없습니다.

필드	타입	값
`unshared_emails`	`list[str]`	A list of user emails those are successfully unshared the virtual folder.

필드	타입	값
(root)	`list[object]`	Virtual Folder List Item Object

예시:

{
   "name": "my cloned folder",
   "id": "b4b1b16c-d07f-4f1f-b60e-da9449aa60a6",
   "host": "local:volume1",
   "usage_mode": "general",
   "created_at": "2020-11-28 13:30:30.912056+00",
   "is_owner": "true",
   "permission": "rw",
   "user": "dfa9da54-4b28-432f-be29-c0d680c7a412",
   "group": null,
   "creator": "admin@lablup.com",
   "user_email": "admin@lablup.com",
   "group_name": null,
   "ownership_type": "user",
   "unmanaged_path": null,
   "cloneable": "false"
}