기술 자료

지원

Cloud Code

Cloud Code

스크립트 구조

Understand the structure of a Cloud Code script and how the main function acts as the entry point.
읽는 시간 2분최근 업데이트: 12시간 전
런타임의 진입점 역할을 하는 Cloud Code 스크립트의 기본 함수는 CommonJS 래퍼의 형태를 띱니다. 다음 코드 스니핏은 가능한 가장 간단한 스크립트의 예시입니다. JavaScript 
module.exports = async ({ params, context, logger }) => {  // this script does nothing};
이 스크립트는 실제로는 아무 작업도 수행하지 않지만, 컨텍스트 오브젝트와 더불어 스크립트 함수의 비동기적인 특성을 보여 줍니다.

컨텍스트 오브젝트

컨텍스트 오브젝트에는 다음과 같은 유용한 오브젝트가 포함되어 있습니다. 
  • Params
    : 스크립트와 함께 호출되는 입력 파라미터의 이름-값 페어 배열입니다.     
  • Context
    : 이 오브젝트는 스크립트 내에서 다음과 같은 유용한 추가 컨텍스트를 제공합니다.     
    • projectId
      : 호출자가 인증을 받은 프로젝트 ID입니다.
    • playerId
      : 인증된 플레이어 ID입니다.
    • accessToken
      : 인증된 플레이어로 다른 Unity 게임 서비스 SDK를 호출하는 데 사용할 수 있는 JWT입니다.
    • environmentName
      : 현재 사용 중인 Unity 환경의 이름입니다.
    • environmentId
      : 현재 사용 중인 Unity 환경의 ID입니다.
    • serviceToken
      : 인증된 Cloud Code 사용자로 다른 Unity 게임 서비스 SDK를 호출하는 데 사용되는 JWT입니다.
    • unityInstallationId
      : 클라이언트 디바이스에서 설치를 식별하는 고유 ID입니다. 동일한 플레이어가 여러 디바이스에 게임을 설치한 경우, 
      installationId
      가 서로 다를 수 있습니다. Services SDK Core 패키지와 연동되는 모든 Unity 패키지에서 사용할 수 있습니다.
    • analyticsUserId
      : 플레이어를 식별하는 고유 문자열로, 분석 목적으로 후속 플레이 세션 전반에서 일관되게 사용됩니다. 이 문자열은 기본 사용자 ID로 Core 패키지에서 제공됩니다.
    • correlationId
      : 요청의 상관 관계를 파악하는 데 사용되는 고유 ID입니다.
  • Logger
    : 스크립트에서 정보, 경고, 오류를 기록하도록 허용하는 오브젝트입니다.

JavaScript

module.exports = async ({logger}) => {  logger.info('This message confirms that the logging client is functional!');  logger.warning('This is a serious warning that the cheese is about to run out.');  logger.error('Out of cheese :(');}
자세한 내용은 로깅 기술 자료를 참고하십시오.

토큰 인증

accessToken
과 
serviceToken
은 
context
오브젝트의 프로퍼티로 제공되는 JWT입니다. 이 토큰은 Cloud Code에서 다른 Unity Gaming Services로의 호출을 인증합니다.

토큰 유형

출처

데이터 액세스

사용

accessToken
Authentication 서비스에서 생성인증된 플레이어로 제한
accessToken
은 Cloud Code 호출과 함께 인증되는 JWT로, 인증된 플레이어의 데이터에 액세스하기 위해 다른 UGS 서비스에 전달할 수 있습니다.
serviceToken
Cloud Code에서 생성크로스 플레이어 데이터 액세스 허용
serviceToken
은 Cloud Code에서 생성된 토큰으로, 다른 UGS 서비스를 호출하고 클로스 플레이어 데이터와 상호 작용하는 데 사용할 수 있습니다.
구성된 모든 액세스 제어 규칙은 
accessToken
에 영향을 줍니다. 아래는 
accessToken
을 사용하여 Economy SDK를 호출하고 플레이어의 인벤토리를 가져오는 방법의 예시입니다.

JavaScript

// Player inventoryconst { InventoryApi } = require("@unity-services/economy-2.4");module.exports = async ({params, context, logger}) => { const { projectId, playerId, accessToken } = context; const inventory = new InventoryApi({accessToken}); const result = await inventory.getPlayerInventory({projectId, playerId}); return result.data;}
serviceToken
을 사용하려는 경우, 위 스크립트를 아래와 같이 바꿔 줍니다.

JavaScript

// Player inventoryconst { InventoryApi } = require("@unity-services/economy-2.4");module.exports = async ({params, context, logger}) => {const { projectId, playerId } = context;const inventory = new InventoryApi(context);const result = await inventory.getPlayerInventory({projectId, playerId});return result.data;}
두 토큰의 차이점에 대한 자세한 설명은 서비스 및 액세스 토큰을 참고하십시오.

스크립트 파라미터

스크립트 파라미터는 스크립트 본문 외부 또는 내부에서 정의할 수 있습니다.

스크립트 내 파라미터

스크립트 내 파라미터는 각 파라미터의 이름을 키로, 파라미터의 유형을 값으로 포함하는 
params
오브젝트를 익스포트해서 추가할 수 있습니다. 예제는 아래와 같습니다.

JavaScript

module.exports.params = { "echo" : "Boolean" }
또는 파라미터를 필수 파라미터로 지정하려는 경우, 
type
과 
required
프로퍼티가 모두 포함된 오브젝트를 지정하면 됩니다.

JavaScript

module.exports = async ({ params, context, logger }) => {    return {        "value": params["aParam"]    };};module.exports.params = { "aParam" : { "type": "String", "required": true } }
기본적으로 파라미터는 필수가 아닙니다. 두 포맷 모두 다음과 같이 원하는 대로 결합할 수 있습니다.

JavaScript

module.exports = async ({ params, context, logger }) => {    var value = params["echo"] ? params["aParam"] : "default";    return {        "value": value    };};module.exports.params = {  "echo" : "Boolean",  "aParam" : { "type": "String", "required": true } }

async/await

기본 스크립트 함수가 비동기 함수일 수 있습니다. 다시 말해서 함수가 프로미스(Promise)를 기다릴 수 있으며, 이를 통해 스크립트 내에서 다른 Unity 게임 서비스 SDK를 사용할 수 있습니다. 프로미스에 대한 설명은 Mozilla 기술 자료(영문)를 참고하십시오. 간단한 예시는 다음과 같습니다.

JavaScript

// Player inventoryconst { InventoryApi } = require("@unity-services/economy-2.4");module.exports = async ({params, context, logger}) => { const { projectId, playerId } = context; const inventory = new InventoryApi(context); const result = await inventory.getPlayerInventory({projectId, playerId}); return result.data;}

추가 패키지

스크립트는 
import
또는 
require
키워드로 로컬 스크립트나 외부 패키지를 임포트할 수 있습니다. 임포트할 수 있는 전체 패키지 목록은 사용 가능한 패키지를 참고하십시오.

JavaScript

const _ = require("lodash-4.17");module.exports = async () => {  return _.random(1, 6);};

번들링

스크립트 번들링은 Unity 에디터 내에서 Deployment 패키지를 사용해서 활성화할 수 있는 기능으로, 이 기능을 사용하면 스크립트를 로컬에서 관리하고, 추가 워크플로를 활용하며, 여러 스크립트에서 공통의 기능을 공유할 수 있습니다. 번들 스크립트를 생성하는 방법을 자세히 알아보려면 JS 번들 기술 자료를 참고하십시오.

JavaScript

const lib = require("./lib");module.exports = async () => {  return lib.helloWorld();};module.exports.bundled = true;

출력

스크립트 출력은 다음과 같은 유형으로 구성될 수 있습니다.

JavaScript

  • string
    module.exports = async () => {  return "hello world";};
  • boolean
    module.exports = async () => {  return true;};
  • number
    module.exports = async () => {  return 3.14;};
  • object
    module.exports = async () => {  return {    message: "hello world",    success: true  };};
성공적인 응답은 API에서 다음과 같은 구조의 JSON으로 반환됩니다. 
{  "output": <SCRIPT OUTPUT>}

오류 출력

서비스 요청이 실패하는 등 호출이 실패하는 원인이 발생하면 스크립트에서 오류가 발생할 수 있습니다. 스크립트 내에서 오류를 포착하면 실패를 처리하는 방식을 정할 수 있습니다.

JavaScript

module.exports = async ({logger}) => {  try {    let result = service.call("example");    return result;  } catch (err) {    logger.error("Something went wrong!", {"error.message": err.message});    throw err;  }};
오류 응답은 API에서 JSON으로 반환되며, 이때 오류의 원인을 파악할 수 있도록 오류 유형, 오류 메시지, 스택 추적을 비롯한 오류 세부 정보를 함께 반환합니다. 
{  "type": "problems/invocation",  "title": "Unprocessable Entity",  "status": 422,  "detail": "Invocation Error",  "instance": null,  "code": 9009,  "details": [      {          "name": "ReferenceError",          "message": "service is not defined",          "stackTrace": [              "at module.exports (example-test.js:1:26)"          ]      }  ]}