메인 콘텐츠로 건너뛰기
playfab service-principal 명령 패밀리는 실험적 기능입니다. CLI 인터페이스는 피드백에 따라 변경되거나 제거될 수 있습니다. CI(연속 통합) 파이프라인 또는 기타 무인 작업은 Microsoft Entra ID 서비스 주체로 로그인합니다. 자동화(서비스 주체) 인증을 참조하세요. PlayFab은 사람이 PlayFab 스튜디오에서 서비스 주체에 액세스 권한을 부여한 후에만 서비스 주체를 허용합니다. 이러한 명령은 해당 권한 부여를 관리합니다. 스튜디오에 대한 Admin 권한이 있는 로그인한 사람만 이러한 명령을 실행할 수 있습니다. XBOX_AUTHENTICATION__MODE가 서비스 주체 모드를 선택하면 이러한 명령은 실행을 거부하므로, 대신 xbox auth login으로 로그인하세요. list는 --output table을 허용하며, 다른 명령은 허용하지 않습니다. list는 한 페이지를 반환합니다. 더 많은 항목이 있으면 응답의 ContinuationToken이 설정되며, --continuation-token을 해당 값으로 설정하여 list를 다시 실행하면 다음 페이지를 가져옵니다.

식별자

  • --studio-id는 권한 부여를 소유한 스튜디오를 지정합니다. 이러한 명령은 PlayFab 타이틀을 사용하지 않으므로 --playfab-title-id와 저장된 컨텍스트가 적용되지 않습니다.
  • --principal-tenant-id와 --principal-object-id는 서비스 주체를 식별합니다. 각각 서비스 주체의 Entra ID 테넌트와, 앱 등록이 아닌 엔터프라이즈 애플리케이션의 개체 ID입니다. 서비스 주체로 로그인하면 xbox auth status가 이를 objectId로 보고합니다.
  • 애플리케이션(클라이언트) ID는 전달하지 않습니다. PlayFab은 서비스 주체의 첫 번째 토큰에서 이를 기록하며, list와 get은 이를 ClientId로 보고합니다.
  • 전역 --tenant-id 및 --client-id 옵션은 액세스 권한을 부여하려는 서비스 주체가 아니라 자신의 로그인을 구성합니다.

권한 부여 파일

set은 서비스 주체의 모든 권한 부여를 --grants-file의 내용으로 대체하며, 파일에서 생략된 스튜디오 권한이나 타이틀을 모두 제거합니다.
파일을 처음부터 작성하지 말고 현재 권한 부여에서 시작하세요. get의 출력을 저장하고, StudioPermissions와 TitleGrants를 편집한 다음, 해당 Version을 --expected-version으로 지정하여 set에 전달하세요.
권한 부여 파일은 get의 전체 출력, 그 data, 그 안의 ServicePrincipal 개체 또는 권한 부여만일 수 있습니다.
  • 두 속성 모두 필수입니다. 빈 목록은 해당 종류의 권한을 부여하지 않습니다.
  • 각 타이틀에는 권한이 하나 이상 필요합니다. 타이틀의 권한 부여를 제거하려면 해당 타이틀을 생략하세요.
  • 속성 이름은 대/소문자를 구분하지 않습니다. 인식할 수 없는 속성은 오류이므로, 철자가 틀린 TitleGrants로 인해 모든 타이틀 권한 부여가 제거되는 일은 없습니다.
  • 파일에 TenantId, ObjectId, DisplayName이 있으면 각각 --principal-tenant-id, --principal-object-id, --display-name과 일치해야 합니다. 서비스 주체의 이름을 바꾸려면 파일의 DisplayName도 변경하거나 제거하세요.

예상 버전

서비스 주체의 권한 부여가 변경될 때마다 새 Version이 부여되며, get과 set이 이를 반환합니다. --expected-version을 사용하면 권한 부여가 여전히 해당 버전인 경우에만 set이 변경하므로, 권한 부여를 읽은 후 다른 사람이 변경한 내용을 되돌릴 수 없습니다. --expected-version 0은 서비스 주체에 아직 액세스 권한이 없어야 함을 요구합니다. --expected-version이 없으면 set은 현재 상태와 관계없이 권한 부여를 대체합니다. 권한 부여 파일에 Version이 있으면 --expected-version이 필요하며 그 값과 같아야 합니다. 값이 다르면 get을 다시 실행하고 해당 출력에서 편집을 다시 수행하세요. 어떤 경우든 권한 부여를 대체하려면 파일에서 Version을 제거하고 --expected-version을 생략하세요.

set이 실패하는 경우

set이 실패하면 set이 성공할 때까지 서비스 주체에 스튜디오 액세스 권한이 없을 수 있으며, 이로 인해 파이프라인이 중단될 수 있습니다.
실패는 권한 부여가 변경되었는지 알려 주지 않으므로, 이전 버전으로 set을 다시 실행하지 마세요. get을 실행하여 권한 부여와 Version을 확인하고, 설정하려던 내용과 다르면 해당 출력을 편집하여 그 Version을 --expected-version으로 지정해 set에 전달하세요.

예제

스튜디오의 서비스 주체를 나열하고, 그중 하나의 권한 부여를 표시합니다.
get에서 저장하여 편집한 grants.json의 권한 부여로 서비스 주체의 권한 부여를 대체합니다.
스튜디오에서 서비스 주체와 해당 권한 부여를 제거합니다.
revoke 후에는 스튜디오에서 서비스 주체의 다음 PlayFab 요청이 실패합니다. revoke는 서비스 주체에 이미 액세스 권한이 없는 경우에도 성공합니다. 액세스 권한을 복원하려면 전체 권한 부여 집합으로 set을 실행하세요.
마지막 수정일 2026년 11월 19일