HTTP API

원시 HTTP API를 사용하여 Cloud Code 스크립트를 관리할 수 있습니다.

API 사용

  • 관리자 API 기술 자료에는 스크립트 생성, 읽기, 업데이트, 삭제 등의 관리자 작업이 자세히 설명되어 있습니다.
  • 클라이언트 API 기술 자료에는 스크립트 실행을 비롯한 클라이언트 측 작업이 자세히 설명되어 있습니다.

두 API 기술 자료 모두 인증, 엔드포인트, 요청, 응답 포맷에 대한 정보와 예시를 소개합니다. OpenAPI 포맷으로 기술 자료를 다운로드하여 직접 자동화를 설정하는 데 활용할 수 있습니다.

관리자 API를 사용하려면 서비스 계정을 사용하여 인증해야 합니다.

스크립트 배포

다음 요청을 전송하여 스크립트를 생성할 수 있습니다.

curl 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <KEY_ID>:<SECRET_KEY>' \
--data '{
    "name": "test-script",
    "type": "API",
    "code": "module.exports = () => {return \"Result from standalone API script\";}",
    "language": "JS"
}'

게임 클라이언트에서 스크립트를 사용하려면 다음과 같이 스크립트를 퍼블리시해야 합니다.

curl --request POST 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts/<SCRIPT_NAME>/publish' \
--header 'Authorization: Basic <KEY_ID>:<SECRET_KEY>'

스크립트를 퍼블리시할 때마다 스크립트 버전의 숫자가 늘어납니다. 성공적인 응답의 예시는 다음과 같습니다.

{
    "version": 1,
    "datePublished": "2023-06-23T10:39:20Z"
}

마지막 퍼블리시 이후 변경 사항이 없는 스크립트는 퍼블리시할 수 없습니다.

스크립트 업데이트

다음 요청을 전송하여 스크립트 코드, 파라미터, 또는 둘 다 업데이트할 수 있습니다.

curl --request PATCH 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts/<SCRIPT_NAME>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <KEY_ID>:<SECRET_KEY>' \
--data '{
    "params": [
        {
            "name": "parameter",
            "type": "STRING",
            "required": false
        }
    ],
     "code": "module.exports = () => {return \"Updated result from standalone API script\";}"
}'

업데이트된 버전의 스크립트를 게임 클라이언트에서 사용하려면, 스크립트를 다시 퍼블리시해서 버전 2를 생성해야 합니다.

{
    "version": 2,
    "datePublished": "2023-06-23T10:40:00Z"
}

스크립트 롤백

스크립트를 퍼블리시했는데 새로운 버전이 마음에 들지 않으면, 지정된 버전 번호로 요청을 전송하여 이전 버전으로 롤백할 수 있습니다.

curl --request POST 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts/<SCRIPT_NAME>/publish' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <KEY_ID>:<SECRET_KEY>'
--data '{
    "version": 1
}'

그러면 다음과 같이 첫 번째 스크립트 버전이 버전 3으로 다시 퍼블리시됩니다.

{
    "version": 3,
    "datePublished": "2023-06-23T10:50:00Z"
}

스크립트 검색

다음 요청을 전송하면 스크립트의 콘텐츠를 확인할 수 있습니다.

curl 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts/<SCRIPT_NAME>' \
--header 'Authorization: Basic <KEY_ID>:<SECRET_KEY>'

응답의 예시는 다음과 같습니다.

{
  "name": "test",
  "type": "API",
  "language": "JS",
  "activeScript": {
    "code": "module.exports=async (cloudCode) =>{cloudCode.logger.info('this message confirms that the logging client is functional!'); return cloudCode.params.someThing;}",
    "params": [
      {
        "name": "someThing",
        "type": "STRING",
        "required": true
      }
    ],
    "version": 2,
    "datePublished": "2021-07-23T16:08:35Z"
  },
  "versions": [
    {
      "code": "module.exports=async (cloudCode) =>{cloudCode.logger.info('this message confirms that the logging client is functional!'); return cloudCode.params.someThing;}",
      "params": [
        {
          "name": "someThing",
          "type": "STRING",
          "required": true
        }
      ],
      "isDraft": true,
      "version": null,
      "dateUpdated": "2021-07-23T15:59:32Z"
    },
    {
      "code": "module.exports=async (cloudCode) =>{cloudCode.logger.info('this message confirms that the logging client is functional!'); return cloudCode.params.someThing;}",
      "params": [
        {
          "name": "someThing",
          "type": "STRING",
          "required": true
        }
      ],
      "isDraft": false,
      "version": 2,
      "dateUpdated": "2021-07-23T16:08:35Z",
      "dateCreated": "2021-07-23T16:08:35Z"
    },
    {
      "code": "module.exports=async (cloudCode) =>{cloudCode.logger.info('this message confirms that the logging client is functional!'); return cloudCode.params.someThing;}",
      "params": [
        {
          "name": "someThing",
          "type": "STRING",
          "required": true
        }
      ],
      "isDraft": false,
      "version": 1,
      "dateUpdated": "2021-07-23T15:59:58Z",
      "dateCreated": "2021-07-23T15:59:58Z"
    }
  ],
  "params": [
    {
      "name": "someThing",
      "type": "STRING",
      "required": true
    }
  ]
}

응답에는 다음과 같은 정보가 포함됩니다.

  • name: 스크립트 이름입니다.
  • type: 스크립트 유형입니다. Cloud Code 스크립트는 API 스크립트만 지원합니다.
  • language: 스크립트 언어입니다. Cloud Code 스크립트는 JavaScript만 지원합니다.

activeScript는 게임 클라이언트에서 사용할 수 있는 현재 퍼블리시된 스크립트 버전을 나타냅니다. 여기에는 해당 스크립트의 코드와 파라미터, 버전 번호, 퍼블리시 날짜가 포함됩니다.

versions 배열에는 현재 퍼블리시된 버전, 작업 중인 사본, 이전에 퍼블리시된 모든 버전 등 스크립트의 모든 버전이 포함됩니다. 작업 중인 사본은 최신 변경 사항이 포함되어 있지만, 아직 게임 클라이언트에서 사용할 수는 없는 버전입니다. 이 버전의 경우, isDraft 속성은 true로, version은 null로 각각 설정됩니다. 작업 중인 사본은 다음에 퍼블리시 요청을 보낼 때 퍼블리시됩니다.

다음 요청을 전송하면 지금까지 생성한 모든 스크립트를 볼 수 있습니다.

curl 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts' \
--header 'Authorization: Basic <KEY_ID>:<SECRET_KEY>'

목록 응답의 예시는 다음과 같습니다.

{
    "results": [
        {
            "name": "script",
            "language": "JS",
            "type": "API",
            "published": true,
            "lastPublishedDate": "2022-03-08T12:37:48Z",
            "lastPublishedVersion": 40
        },
        {
            "name": "test",
            "language": "JS",
            "type": "API",
            "published": true,
            "lastPublishedDate": "2023-06-20T15:14:58Z",
            "lastPublishedVersion": 4
        }
    ],
    "links": {
        "next": null
    }
}

응답에는 생성한 모든 스크립트의 간략한 개요가 포함되어 있습니다. 파라미터로 결과의 범위를 좁히고 다음 결과 페이지로 연결되는 링크를 확보하면 페이지 매김을 사용할 수 있습니다.

curl 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts?limit=2' \
--header 'Authorization: Basic <KEY_ID>:<SECRET_KEY>'

다음 결과 링크의 예시는 다음과 같습니다.

{
  "links": {
        "next": "/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts?after=<SCRIPT_NAME>"
    }
}

스크립트 삭제

다음 요청을 전송하면 스크립트를 삭제할 수 있습니다.

curl --request DELETE 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts/<SCRIPT_NAME>' \
--header 'Authorization: Basic <KEY_ID>:<SECRET_KEY>'

빈 응답은 삭제에 성공했음을 나타냅니다.

Unity logo Documentation
Copyright © 2025 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.