> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/networking/network-connections.md). # 네트워크 연결 씬을 외부 서버 및 API와 통신시키는 방법입니다. 여러분의 씬은 API를 공개하는 외부 서비스를 활용할 수 있으며, 이를 사용해 최신 가격 데이터, 날씨 데이터 또는 API를 통해 제공되는 다른 종류의 정보를 가져올 수 있습니다. 또한 씬을 돕고 플레이어 간 데이터를 동기화하는 데 사용할 자체 외부 서버를 설정할 수도 있습니다. 이는 REST API를 공개하는 서버로 하거나, WebSocket을 사용하는 서버로 구현할 수 있습니다. ## REST API 호출 씬의 코드는 REST API에 호출을 보내 데이터를 가져올 수 있습니다. 서버가 응답을 보내는 데 시간이 걸릴 수 있으므로, 이 명령은 [비동기 함수로](/creator/content-creator-ko/sdk7/programming-patterns/async-functions.md), 사용하여 `executeTask()`. ```ts executeTask(async () => { try { let response = await fetch(callUrl) let json = await response.json() console.log(json) } catch { console.log('URL에 연결하지 못했습니다') } }) ``` fetch 명령에는 헤더, HTTP 메서드, HTTP 본문을 하나의 객체로 묶는 두 번째 선택적 인수도 포함할 수 있습니다. * **url**: 요청을 보낼 주소 * **init**: `RequestInit` 객체로, 다음을 포함할 수 있습니다: * **method** : 사용할 HTTP 메서드(GET, POST, DELETE 등) * **body**: 요청 본문의 내용. 문자열화된 JSON 객체로 전송해야 합니다. * **headers**: 요청에 포함할 추가 헤더. * **redirect**: 리디렉션 전략('follow' | 'error' | 'manual') * **timeout**: 요청이 실패하기 전에 응답을 기다릴 시간. 기본값은 30000밀리초(30초)입니다. ```ts executeTask(async () => { try { let response = await fetch(callUrl, { headers: { 'Content-Type': 'application/json' }, method: 'POST', body: JSON.stringify(myBody), }) let json = await response.json() console.log(json) } catch { console.log('URL에 연결하지 못했습니다') } }) ``` fetch 명령은 다음 데이터가 포함된 `response` 객체를 반환합니다: * `headers`: `ReadOnlyHeaders` 객체입니다. 특정 헤더를 가져오려면 `get()` 메서드를 호출하거나, `has()` 메서드를 호출해 헤더가 존재하는지 확인합니다. * `ok`: Boolean * `redirected`: Boolean * `status`: 상태 코드 번호 * `statusText`: 상태 코드의 텍스트 * `type`: 다음 값 중 하나를 갖습니다: *basic*, *cors*, *default*, *error*, *opaque*, *opaqueredirect* * `url`: 전송된 URL * `json()`: 본문을 JSON 형식으로 가져옵니다. * `text()`: 본문을 텍스트로 가져옵니다. {% hint style="warning" %} **📔 참고**: `json()` 및 `text()` 는 서로 배타적입니다. 응답 본문을 두 형식 중 하나로 가져오면, 더 이상 다른 형식은 `response` 객체. {% endhint %} {% hint style="warning" %} **📔 참고**: 각 Decentraland 씬은 한 번에 하나의 `fetch` 명령만 실행할 수 있습니다. 요청은 내부적으로 대기열에 들어가므로, 이는 씬 코드의 구조 방식에는 영향을 주지 않습니다. 씬이 여러 엔드포인트에 여러 요청을 보내야 한다면, 각 요청은 이전 요청에 대한 응답이 온 후에만 전송된다는 점을 기억하세요. {% endhint %} ## 서명된 요청 요청이 Decentraland 내부의 플레이어 세션에서 비롯되었음을 인증하기 위해 추가 보안 조치를 사용할 수 있습니다. 각 플레이어의 주소를 기반으로 Decentraland 세션이 생성하는 임시 키로 서명된 추가 서명을 포함해 요청을 보낼 수 있습니다. 그런 다음 요청을 받는 서버는 서명된 메시지가 실제로 월드에서 현재 활성 상태인 주소와 일치하는지 확인할 수 있습니다. 이러한 보안 조치는 플레이어가 시스템을 악용하여 게임에서 토큰이나 점수를 파밍할 유인이 있을 수 있을 때 특히 유용합니다. 서명된 요청을 보내려면, 다음 함수를 사용하기만 하면 됩니다. `signedFetch()` 를 사용하는 것과 정확히 같은 방식으로 `fetch()` 함수를 실행 중이라고 가정합니다. ```ts import { signedFetch } from '~system/SignedFetch' executeTask(async () => { try { let response = await signedFetch({ url: callUrl, init: { headers: { 'Content-Type': 'application/json' }, method: 'POST', body: JSON.stringify(myBody), }, }) if (!response.ok) { throw new Error('Invalid response') } let json = JSON.parse(response.body) console.log('Response received: ', json) } catch { console.log('URL에 연결하지 못했습니다') } }) ``` 요청에는 추가 헤더 묶음이 포함되며, 여기에는 서명된 메시지와 이를 해석하기 위한 메타데이터 세트가 들어 있습니다. 서명된 메시지는 플레이어의 임시 키를 사용해 암호화된 요청의 모든 내용으로 구성됩니다. 그 `signedFetch()` 는 `fetch()` 함수와 다르며, 응답은 다음과 같이 표현되는 전체 HTTP 메시지에 대한 promise입니다. `FlatFetchResponse` 객체입니다. 여기에는 다음 속성이 포함됩니다: * `body` * `headers` * `ok` * `status` * `statusText` 그 **body** 는 항상 문자열이며, 위의 예시처럼 파싱할 수 있습니다. ### 서명된 요청 검증 서명된 요청을 활용하려면, 이를 받는 서버는 서명이 나머지 요청 내용과 일치하는지, 그리고 서명된 메시지에 인코딩된 타임스탬프가 현재인지 검증해야 합니다. 다음 예시 씬에서 이 작업을 수행하는 서버의 간단한 예를 찾을 수 있습니다: [플레이어 진위 검증](https://github.com/decentraland-scenes/validate-player-authenticity) ## 요청 시간 초과 HTTP 요청이 응답되기까지 너무 오래 걸리면 실패하여 다른 요청을 보낼 수 있습니다. 이 경우 `fetch()`기본 시간 초과 임계값은 30초이지만, 요청마다 다음을 구성하여 다른 값을 지정할 수 있습니다. `timeout` 속성. 의 값은 `timeout` 밀리초 단위로 표현됩니다. ```ts fetch('https://some-url.com', { timeout: 1000 }) ``` ## WebSocket 사용 또한 WebSocket 서버와 데이터를 주고받을 수 있습니다. 단, 이 서버가 다음을 사용하는 보안 연결을 통해야 합니다 *wss*. ```ts var socket = new WebSocket('url') socket.onmessage = function (event) { console.log('WebSocket message received:', event) } ``` WebSocket을 사용하는 구문은 JavaScript에서 기본으로 구현된 것과 다르지 않습니다. 다음 문서를 참고하세요 [Mozilla Web API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) 에서 WebSocket을 통해 메시지를 수신하고 전송하는 방법에 대한 자세한 내용을 확인하세요. {% hint style="info" %} **💡 팁**: WebSocket 연결 사용을 단순화하고 Decentraland에서 매우 잘 동작하는 것으로 입증된 한 라이브러리는 [Colyseus](https://colyseus.io/). 여러 다른 WebSocket 라이브러리는 Decentraland SDK와 호환되지 않습니다. WebSocket 연결 위에 추상화 계층을 구축해 변경 사항에 반응하고 서버에서 일관된 게임 상태를 원격으로 저장하는 일을 아주 쉽게 만들어 줍니다. 다음 예시에서 실제 작동 모습을 볼 수 있습니다: * [Cube Jumper](https://github.com/decentraland-scenes/cube-jumper-colyesus-sdk7) * [Space Traitor](https://github.com/decentraland-scenes/Space-Traitor) * [AI NPC](https://github.com/decentraland-scenes/inworld-ai-sdk7) {% endhint %} ## 네트워크 요청 디버깅 Debug Panel을 열어 네트워크 요청을 디버깅할 수 있습니다. Debug Panel을 열려면 ![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-92fe4dd70621a496d0da083ae9b5f9b2ef84d2dd%2Fdebug-icon.png?alt=media) 오른쪽 상단 모서리의 아이콘을 클릭하세요. 그런 다음 **웹 요청** 탭을 선택하고 **Chrome DevTools 열기**. Chrome 새 창이 열리며 Network 탭이 열려 있습니다. 참고 [미리보기에서 디버그](/creator/content-creator-ko/sdk7/debugging/debug-in-preview.md#web-requests) 자세한 내용은 다음을 참조하세요. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/networking/network-connections.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.