본문 바로가기
WIKI 기술 지식 베이스

Resource sharing APIs

원문 보기 위키 갱신

출처: 문서

본문

리소스 공유 API

3.3부터 도입 {: .label .label-purple }

Resource Sharing API는 플러그인이 정의한 리소스에 대해 세분화된 문서 수준 접근 제어를 프로그래밍 방식으로 관리할 수 있게 해줘요. 이 API를 사용하면 리소스를 공유하고, 접근 권한을 관리하고, 리소스 공유 워크플로를 자동화할 수 있어요.

이 REST API를 사용하면 리소스 공유를 직접 관리할 수 있어요. 작업은 리소스의 소유자이거나, superadmin이거나, 해당 리소스에 대한 공유 접근 권한이 있는 경우에만 수행할 수 있어요.

레거시 공유 메타데이터 마이그레이션

플러그인이 관리하던 레거시 공유 메타데이터를 가져와요. 이 API는 시스템 마이그레이션 중에 관리자가 한 번만 실행하도록 설계됐어요.

엔드포인트

POST _plugins/_security/api/resources/migrate

요청 본문 필드

다음 표는 사용 가능한 요청 본문 필드를 보여줘요.

필드 데이터 타입 설명
source_index String 레거시 공유 메타데이터가 담긴 소스 인덱스예요. 필수예요.
username_path String 소유자 이름을 가리키는 JSON 경로예요(예: /owner/name). 필수예요.
backend_roles_path String 백엔드 역할을 가리키는 JSON 경로예요(예: /owner/backend_roles). 필수예요.
default_owner String 명시적인 소유자가 없는 리소스에 적용되는 기본 소유자예요. 필수예요.
default_access_level Object 리소스 타입별 기본 접근 수준이에요. 리소스 인덱스에 여러 리소스 타입이 들어 있다면 항목을 추가로 넣어 주세요. 필수예요.

예제 요청

POST _plugins/_security/api/resources/migrate
{
  "source_index": "legacy-sharing-index",
  "username_path": "/owner/name",
  "backend_roles_path": "/owner/backend_roles",
  "default_owner": "admin",
  "default_access_level": {
    "ml-model-group": "read_only",
    "anomaly-detector": "read_write"
  }
}

{% include copy-curl.html security=true %}

예제 응답

{
  "summary": "Migration complete. migrated 10; skippedNoType 1; skippedExisting 0; failed 1",
  "resourcesWithDefaultOwner": ["doc-17"],
  "skippedResources": ["doc-22"]
}

응답 본문 필드

다음 표는 모든 응답 본문 필드를 보여줘요.

필드 데이터 타입 설명
summary String 마이그레이션 결과를 설명하는 요약 메시지예요. 마이그레이션된 리소스, 건너뛴 리소스, 실패한 리소스의 개수가 포함돼요.
resourcesWithDefaultOwner Array 소유자 정보를 찾지 못해 기본 소유자가 할당된 리소스 ID 목록이에요.
skippedResources Array 마이그레이션 중 건너뛴 리소스 ID 목록이에요(예: 타입 정보가 없거나 이미 마이그레이션된 경우).

필수 권한

Security 플러그인을 사용한다면 적절한 권한을 갖고 있는지 확인하세요: restapi:admin/resource_sharing/migrate.

공유 구성 조회

특정 리소스의 현재 공유 구성을 조회해요.

엔드포인트

GET _plugins/_security/api/resource/share

쿼리 파라미터

다음 표는 사용 가능한 쿼리 파라미터를 보여줘요.

파라미터 데이터 타입 설명
resource_id String 리소스의 고유 식별자예요. 필수예요.
resource_type String 리소스의 타입이에요(예: ml-model-group). 필수예요.

예제 요청

GET _plugins/_security/api/resource/share?resource_id=model-group-123&resource_type=ml-model-group

{% include copy-curl.html security=true %}

예제 응답

{
  "sharing_info": {
    "resource_id": "model-group-123",
    "created_by": {
      "user": "admin"
    },
    "share_with": {
      "read_only": {
        "users": ["bob"],
        "roles": ["data_viewer"],
        "backend_roles": []
      },
      "read_write": {
        "users": ["charlie"],
        "roles": [],
        "backend_roles": ["ml_team"]
      }
    }
  }
}

응답 본문 필드

다음 표는 모든 응답 본문 필드를 보여줘요.

필드 데이터 타입 설명
sharing_info Object 리소스의 전체 공유 구성을 담고 있어요.
sharing_info.resource_id String 리소스의 고유 식별자예요.
sharing_info.created_by Object 리소스 생성자에 대한 정보예요.
sharing_info.created_by.user String 리소스 생성자의 사용자 이름이에요.
sharing_info.share_with Object 접근 수준별로 정리된 공유 구성이에요.
sharing_info.share_with.<access_level> Object 주체 목록을 담고 있는 접근 수준이에요(예: read_only, read_write).
sharing_info.share_with.<access_level>.users Array 이 접근 수준을 가진 사용자 이름 목록이에요.
sharing_info.share_with.<access_level>.roles Array 이 접근 수준을 가진 역할 목록이에요.
sharing_info.share_with.<access_level>.backend_roles Array 이 접근 수준을 가진 백엔드 역할 목록이에요.

필수 권한

Security 플러그인을 사용한다면 적절한 권한을 갖고 있는지 확인하세요: cluster:admin/security/resource/share.

리소스 공유 구성 교체

리소스의 공유 구성을 완전히 교체해요. 이 작업은 기존의 모든 공유 설정을 덮어써요.

엔드포인트

PUT _plugins/_security/api/resource/share

요청 본문 필드

다음 표는 사용 가능한 요청 본문 필드를 보여줘요.

필드 데이터 타입 설명
resource_id String 리소스의 고유 식별자예요. 필수예요.
resource_type String 리소스의 타입이에요. 필수예요.
share_with Object 접근 수준별로 정리된 공유 구성이에요. 각 접근 수준은 users, roles, backend_roles 배열을 담을 수 있어요. 필수예요.

예제 요청: 특정 사용자 및 역할과 공유하기

PUT _plugins/_security/api/resource/share
{
  "resource_id": "model-group-123",
  "resource_type": "ml-model-group",
  "share_with": {
    "read_only": {
      "users": ["bob"],
      "roles": ["data_viewer"]
    },
    "read_write": {
      "users": ["charlie"],
      "backend_roles": ["ml_team"]
    }
  }
}

{% include copy-curl.html security=true %}

예제 요청: 리소스를 비공개로 만들기

PUT _plugins/_security/api/resource/share
{
  "resource_id": "model-group-123",
  "resource_type": "ml-model-group",
  "share_with": {}
}

{% include copy-curl.html security=true %}

예제 응답

{
  "sharing_info": {
    "resource_id": "model-group-123",
    "created_by": {
      "user": "admin"
    },
    "share_with": {
      "read_only": {
        "users": ["bob"],
        "roles": ["data_viewer"],
        "backend_roles": []
      },
      "read_write": {
        "users": ["charlie"],
        "roles": [],
        "backend_roles": ["ml_team"]
      }
    }
  }
}

응답 본문 필드

다음 표는 모든 응답 본문 필드를 보여줘요.

필드 데이터 타입 설명
sharing_info Object 리소스의 전체 공유 구성을 담고 있어요.
sharing_info.resource_id String 리소스의 고유 식별자예요.
sharing_info.created_by Object 리소스 생성자에 대한 정보예요.
sharing_info.created_by.user String 리소스 생성자의 사용자 이름이에요.
sharing_info.share_with Object 접근 수준별로 정리된 공유 구성이에요.
sharing_info.share_with.<access_level> Object 주체 목록을 담고 있는 접근 수준이에요(예: read_only, read_write).
sharing_info.share_with.<access_level>.users Array 이 접근 수준을 가진 사용자 이름 목록이에요.
sharing_info.share_with.<access_level>.roles Array 이 접근 수준을 가진 역할 목록이에요.
sharing_info.share_with.<access_level>.backend_roles Array 이 접근 수준을 가진 백엔드 역할 목록이에요.

필수 권한

Security 플러그인을 사용한다면 적절한 권한을 갖고 있는지 확인하세요: cluster:admin/security/resource/share.

리소스 공유 구성 업데이트

기존 공유 구성에 영향을 주지 않으면서 접근 권한을 추가하거나 제거해요. 이 작업은 비파괴적이라 현재 접근 설정이 그대로 유지돼요.

엔드포인트

PATCH _plugins/_security/api/resource/share

요청 본문 필드

다음 표는 사용 가능한 요청 본문 필드를 보여줘요.

필드 데이터 타입 설명
resource_id String 리소스의 고유 식별자예요. 필수예요.
resource_type String 리소스의 타입이에요. 필수예요.
add Object 추가할 접근 권한이에요. 접근 수준별로 정리돼요. 선택 사항이에요.
revoke Object 제거할 접근 권한이에요. 접근 수준별로 정리돼요. 선택 사항이에요.

예제 요청: 접근 권한을 동시에 추가하고 제거하기

PATCH _plugins/_security/api/resource/share
{
  "resource_id": "model-group-123",
  "resource_type": "ml-model-group",
  "add": {
    "read_only": { "users": ["dave"] }
  },
  "revoke": {
    "read_write": { "users": ["charlie"] }
  }
}

{% include copy-curl.html security=true %}

예제 요청: 리소스를 공개로 만들기

PATCH _plugins/_security/api/resource/share
{
  "resource_id": "model-group-123",
  "resource_type": "ml-model-group",
  "add": {
    "read_only": { "users": ["*"] }
  }
}

{% include copy-curl.html security=true %}

예제 요청: 특정 접근 권한 제거하기

PATCH _plugins/_security/api/resource/share
{
  "resource_id": "model-group-123",
  "resource_type": "ml-model-group",
  "revoke": {
    "read_write": { "users": ["charlie"] }
  }
}

{% include copy-curl.html security=true %}

예제 응답

{
  "sharing_info": {
    "resource_id": "model-group-123",
    "created_by": {
      "user": "admin"
    },
    "share_with": {
      "read_only": {
        "users": ["bob", "dave"],
        "roles": ["data_viewer"],
        "backend_roles": []
      },
      "read_write": {}
    }
  }
}

응답 본문 필드

다음 표는 모든 응답 본문 필드를 보여줘요.

필드 데이터 타입 설명
sharing_info Object 수정 후 리소스의 전체 공유 구성을 담고 있어요.
sharing_info.resource_id String 리소스의 고유 식별자예요.
sharing_info.created_by Object 리소스 생성자에 대한 정보예요.
sharing_info.created_by.user String 리소스 생성자의 사용자 이름이에요.
sharing_info.share_with Object 접근 수준별로 정리된, 업데이트된 공유 구성이에요.
sharing_info.share_with.<access_level> Object add/revoke 작업 후 주체 목록을 담고 있는 접근 수준이에요.
sharing_info.share_with.<access_level>.users Array 이 접근 수준을 가진 사용자 이름 목록이에요.
sharing_info.share_with.<access_level>.roles Array 이 접근 수준을 가진 역할 목록이에요.
sharing_info.share_with.<access_level>.backend_roles Array 이 접근 수준을 가진 백엔드 역할 목록이에요.

필수 권한

Security 플러그인을 사용한다면 적절한 권한을 갖고 있는지 확인하세요: cluster:admin/security/resource/share.

접근 가능한 리소스 목록 조회

조회하거나 관리할 수 있는, 특정 타입의 모든 리소스를 반환해요.

엔드포인트

GET _plugins/_security/api/resource/list

쿼리 파라미터

다음 표는 사용 가능한 쿼리 파라미터를 보여줘요.

파라미터 데이터 타입 설명
resource_type String 목록을 조회할 리소스의 타입이에요. 필수예요.

예제 요청

GET _plugins/_security/api/resource/list?resource_type=ml-model-group

{% include copy-curl.html security=true %}

예제 응답

{
  "resources": [
    {
      "resource_id": "model-group-123",
      "created_by": {
        "user": "admin",
        "tenant": "default"
      },
      "share_with": {
        "read_only": {
          "users": ["bob"]
        }
      },
      "can_share": true
    },
    {
      "resource_id": "model-group-456",
      "created_by": {
        "user": "alice",
        "tenant": "default"
      },
      "can_share": false
    }
  ]
}

응답 본문 필드

다음 표는 모든 응답 본문 필드를 보여줘요.

필드 데이터 타입 설명
resources Array 인증된 사용자가 접근할 수 있는 리소스 목록이에요.
resources[].resource_id String 리소스의 고유 식별자예요.
resources[].created_by Object 리소스 생성자에 대한 정보예요.
resources[].created_by.user String 리소스 생성자의 사용자 이름이에요.
resources[].created_by.tenant String 리소스 생성자와 연관된 테넌트예요(해당하는 경우).
resources[].share_with Object 이 리소스의 공유 구성이에요. 리소스가 아직 공유되지 않았다면 이 필드가 없을 수도 있어요.
resources[].share_with.<access_level> Object 주체 목록을 담고 있는 접근 수준이에요.
resources[].share_with.<access_level>.users Array 이 접근 수준을 가진 사용자 이름 목록이에요.
resources[].can_share Boolean 인증된 사용자가 이 리소스를 공유할 권한이 있는지 나타내요.

필수 권한

이 API는 인증된 접근이 필요하지만 특별한 클러스터 권한은 필요하지 않아요.

리소스 타입 목록 조회

공유 가능한 모든 리소스 타입과 지원되는 접근 수준을 반환해요. OpenSearch Dashboards는 이 API를 사용해 리소스 타입별로 지원되는 접근 수준을 판단해요.

엔드포인트

GET _plugins/_security/api/resource/types

예제 요청

GET _plugins/_security/api/resource/types

{% include copy-curl.html security=true %}

예제 응답

{
  "types": [
    {
      "type": "ml-model-group",
      "action_groups": ["ml_read_only", "ml_read_write", "ml_full_access"]
    },
    {
      "type": "anomaly-detector",
      "action_groups": ["ad_read_only", "ad_full_access"]
    }
  ]
}

응답 본문 필드

다음 표는 모든 응답 본문 필드를 보여줘요.

필드 데이터 타입 설명
types Array 시스템에서 사용할 수 있는 리소스 타입 목록이에요.
types[].type String 리소스 타입의 이름이에요.
types[].action_groups Array 이 리소스 타입에 사용할 수 있는 액션 그룹(접근 수준) 목록이에요.

필수 권한

이 API는 인증된 접근이 필요하지만 특별한 클러스터 권한은 필요하지 않아요.

관련 문서

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.