xbox)는 사람뿐만 아니라 AI 에이전트와 스크립트도 실행할 수 있도록 빌드되었습니다. 해당
명령은 명시적 인수를 받고, 데이터 명령은 JSON을 작성하며, 오류는 0이 아닌 종료 코드와 함께
stderr로 전달됩니다. 이 페이지는 에이전트와 에이전트를 설정하는 사람을 위한 것으로,
로그인하는 방법, 명령의 작업 대상을 선택하는 방법, 출력을 읽는 방법, 올바른 API를 찾는 방법, 그리고
변경하기 전에 확인해야 할 사항을 설명합니다.
변경하기 전에
로그인한 사용자는 일반적으로 프로덕션 타이틀과 판매자에 대한 관리자 권한을 가지고 있으며, 서버 측에서는 잘못된 호출을 막지 않습니다. 안전 및 파괴적 작업에는 CLI가 확인을 요청하는 항목과 요청하지 않는 항목이 나와 있습니다. 나머지는 에이전트의 책임입니다.- PlayFab 작업은 이름이
Get,List또는Search로 시작하는 경우에만 읽기 전용으로 취급하세요. 그 밖의 모든 작업과 무언가를 만들거나, 변경하거나, 삭제하는 모든xbox명령은 프로덕션 변경으로 취급하세요. - 프로덕션 변경 전에 사용자에게 명령을 보여 주고, 무엇을 어떤 타이틀 또는 판매자에서
변경하는지(해당 대상이 저장된 컨텍스트에서 오는지 여부 포함) 한 문장으로 설명하세요.
런타임이 확인 없이
xbox를 실행할 수 있더라도 사용자가 승인한 후에만 실행하세요. 승인은 보여 준 호출에만 적용됩니다. - 모든 프로덕션 변경에서 타이틀 또는 판매자를 플래그로 전달하세요. 저장된 컨텍스트는 해당 OS 사용자의 모든 세션에서 공유되므로 사용자의 승인과 에이전트의 호출 사이에 변경될 수 있습니다.
- PC의 모든 사용자에 대해 샌드박스를 전환하는
xbox pc sandbox set과 Microsoft Store 및 XBOX 앱을 닫는xbox pc sandbox launch-apps전에는 확인을 요청하세요. - 확인 요청 대신
--confirm(또는--yes)을 추가하지 마세요. CLI는 누가 이를 추가했는지 알 수 없습니다. xbox xbl config publish로 RETAIL에 게시하도록 요청하기 전에--validate-only와 함께 실행하고 나열된 업적을 사용자에게 보여 주세요. 그런 다음 JSON 출력의SourceVersion으로--configset을 설정하여 게시하세요. RETAIL의 업적은 제거할 수 없습니다. RETAIL 게시로 추가되는 업적을 참조하세요.- 프로덕션 변경이 실패하고 결과를 알 수 없는 경우 변경이 적용되었을 수 있습니다. 다시 시도하기 전에 영향을 받는 상태를 읽으세요. 중단된 쓰기는 결과를 알 수 없다고 보고함을 참조하세요.
- 사용자가 요청하지 않는 한 저장된 컨텍스트를 변경하지 마세요.
xbox context set,xbox context unset및xbox context profile delete는 모든 세션의 기본값을 변경합니다.
로그인
auth status는 로그인한 사용자가 없으면 코드 0으로 종료하고 {"signedIn":false}를 보고하므로
signedIn을 기준으로 분기하세요. 0이 아닌 종료 코드는 확인할 수 없었음을 의미하며, 오류는 stderr에 있습니다.
로그인한 사용자에게 타이틀에 대한 Admin 권한이 없으면 PlayFab 호출이 실패합니다.
인증을 참조하세요.
타이틀 또는 판매자 선택
--playfab-title-id ABC123처럼 타이틀 또는 판매자를 플래그로 전달하세요. 플래그가 없으면
명령은 XBOX_ 환경 변수 또는 xbox context set으로 저장된 값을 사용합니다. 어느 쪽이 우선하는지는
컨텍스트를 참조하세요. 저장된 내용을 확인하려면
xbox context get --output json-compact를 실행하고, 실질적인 호출을 하기 전에 사용자와
타이틀을 한 번 확인하세요.
출력 읽기
--data-only와 --output json-compact를 함께 사용하면 페이로드만 한 줄로 가져올 수 있습니다.
--data-only를 사용하면 오류 시 stdout이
비어 있으므로 stdout을 구문 분석하기 전에 종료 코드를 확인하세요.
playfab file upload, download 및 delete는 stdout에 아무것도 작성하지 않으며 stderr
메시지는 변경될 수 있으므로 종료 코드를 확인하세요. 파일을 참조하세요.
도움말은 인터페이스가 변경될 수 있는 Experimental 명령을 표시합니다.
실험적 명령을 참조하세요.
속도 제한
XBOX 서비스가 HTTP 429로 응답하면 잠시 기다린 후 다시 시도하세요. CLI는 자동으로 다시 시도하지 않습니다. 서비스가 대기 시간을 지정하면 오류에 몇 초인지 표시되며, 구조화된 오류에도retryAfterSeconds로 포함됩니다. 오류 코드 rate_limited가 있는 429는 짧은 시간에 너무
많은 요청을 보냈다는 의미이므로 속도를 늦추세요.
올바른 PlayFab API 찾기
xbox playfab api <api-path>는 모든 PlayFab API 작업을 호출합니다. 경로는
/MultiplayerServer/ListBuildSummariesV2와 같은 /<Prefix>/<Operation>이며, 요청
본문은 작업의 JSON 요청 개체입니다. PlayFab은 두 가지를 모두 문서화합니다.
- PlayFab Swagger 사양은
컴퓨터가 읽을 수 있는 형식입니다. 각 파일에는 요청 및 응답 스키마와 필수 필드와 함께
작업이 경로별로 나열되어 있습니다. 파일 이름은 경로의 첫 번째 세그먼트가 아니라 PlayFab의 API 그룹을
기준으로 지정되므로, 파일의
paths에서 작업을 검색하세요./Catalog및/Inventory는Economy.swagger.json에 있고,/Match,/Lobby및/MultiplayerServer는Multiplayer.swagger.json에 있습니다. 각 작업의security필드는 허용되는 자격 증명을 지정합니다.SecretKey,EntityToken,SessionTicket또는 플레이어 로그인 호출처럼 자격 증명이 필요 없는 작업의 경우None입니다. 일부 작업은 설명에 허용되는 엔터티 토큰 유형도 나열합니다. - PlayFab REST API 참조는 사람을 위해 동일한 작업을 다룹니다.
SessionTicket이 필요하거나 플레이어 또는 게임 서버 엔터티 토큰만 허용하는 작업은
권한이 부여되지 않습니다. 호출이 실패하면 오류 응답에 일반적으로 InvalidParameter 또는
MissingParameter처럼 문제가 무엇인지 표시됩니다. 자세한 내용은 PlayFab API 통합을
참조하세요.
Windows의 Git Bash에서는 명령에 MSYS_NO_PATHCONV=1을 설정하세요. 그렇지 않으면 Git Bash가
CLI에 전달하기 전에 API 경로를 Windows 경로로 변환합니다.
Windows의 Git Bash에서 실행을 참조하세요.
로그에 비밀이 남지 않도록 하기
- 요청 본문에 비밀이 포함될 수 있는 경우
--body대신--body-file로 전달하여 셸 기록과 프로세스 목록에 남지 않도록 하세요.playfab mps certificate upload및playfab mps secret upload는 본문에 항상 비밀이 포함되므로--body를 거부합니다. - 구성 파일과 환경 변수에 비밀을 두지 마세요.
ClientId,TenantId및 OAuth 범위는 비밀이 아니라 식별자입니다. - PlayFab 응답에는 플레이어, 인벤토리 또는 경제 데이터가 포함될 수 있습니다. 에이전트가 로그에 기록하는 내용의 수정, 보존 및 액세스 제어는 에이전트 소유자의 책임입니다.
참고 항목
- 명령: 전체 명령 참조
- 안전 및 파괴적 작업: 먼저 확인을 요청하는 항목과 이름이 나타내는 것보다 더 많은 작업을 수행하는 항목
