본문으로 건너뛰기

Remote - HTTP 클라이언트

소개​

애플리케이션에서는 종종 외부 서비스로 HTTP 요청을 보내야 합니다. 이는 _remote 리소스를 사용하여 수행할 수 있습니다.

컴퓨터의 다른 서비스나 내부 서버로 내부 HTTP 호출을 하거나 인터넷의 서비스를 호출하려면 Remote 리소스를 사용하는 것이 필수적입니다.

Remote 리소스 문서를 참조하세요.

JSON으로 데이터를 주고받고 파일을 업로드하거나 다운로드할 수도 있습니다.

초기화​

HTTP 호출을 수행하려면 먼저 호출을 초기화해야 합니다. 이를 위해 _remote의 init 메서드를 사용하고, 그 결과를 원격이라는 변수에 저장하여 요청을 참조할 수 있도록 합니다:

// HTTP 매개변수 전송 지원
const 간단한원격 = _remote.init();
// JSON 전송 지원:
const json원격 = _remote.init().asJSON();

구성​

애플리케이션에서 전역 구성을 정의할 수도 있습니다. 다음 전체 예제를 확인하세요:

  ...
  "remote": { 
    "예제-기본-인증": {
      "url": "https://exemplo.com/api/rest/exemplo",
      "form": true,
      "authorization": {
        "username": "관리자",
        "password": "비밀번호"
      },
      "data": {
        "매개변수1": "값 1...",
        "매개변수2": "값 2..."
      }
    },
    "예제-인증-토큰": {
      "urlPrefix": "https://exemplo.com/api",
      "json": true,
      "authorization": "Bearer 여기에-인증-토큰",
      "connectTimeout": 5000,
      "readTimeout": 60000,
    }
  },
  ...

URL 접두사(urlPrefix) 또는 전체 URL(url)을 구성할 수 있습니다.

요청이 기본적으로 데이터를 Form 또는 JSON으로 전송할지 정의할 수 있습니다.

로그인과 비밀번호를 사용하는 기본 인증 또는 토큰 인증 전송을 지원합니다.

또한 전송할 기본 데이터(data)와 연결 제한 시간(connectTimeout) 및 읽기 제한 시간(readTimeout)을 정의할 수 있습니다.

사용 방법​

애플리케이션에 정의된 구성으로 Remote 리소스를 사용하려면 구성 키로 리소스를 초기화하기만 하면 됩니다. 예:

const 응답 = _remote.init("예제-기본-인증").post();

URL 접두사가 정의된 경우:

const 원격 = _remote.init("예제-인증-토큰");
const 응답 = 원격.post(
  "/services/데이터-불러오기",
  _val.map()
    .set("매개변수1", "값 1")
    .set("매개변수2", "값 2")
);

HTTP 요청​

Remote 리소스를 사용하여 HTTP 요청을 시작하는 방법을 확인하세요.

JSON 전송​

JSON 형식으로 데이터를 전송하려면 콘텐츠 유형을 JSON으로 지정해야 합니다:

간단한 방법은 asJSON() 메서드를 사용하는 것입니다. 예:

const 원격 = _remote.init().asJSON();
원격.setURL("http://exemplo.com/salva");
const 응답 = 원격.post(
  _val.map()
    .set("데이터", "예제")
    .set("JSON", true)
);

따라서 데이터는 POST 및 PUT HTTP 메서드에서는 JSON으로 전송되지만, GET 및 DELETE의 경우 이러한 메서드는 HTTP 프로토콜에서 데이터 본문을 지원하지 않으므로 데이터가 항상 쿼리스트링으로 전송됩니다.

HTTP 메서드​

호출 헤더에 HTTP 메서드를 명시적으로 지정할 필요는 없습니다. 호출 참조에는 각 HTTP 메서드 유형에 대한 전용 함수가 있습니다:

const 원격 = _remote.init();

원격.setURL("http://exemplo.com");

원격.get(); // GET 호출용
원격.post(); // POST 호출용
원격.put(); // PUT 호출용
원격.delete(); // DELETE 호출용

HTTP 헤더​

HTTP 헤더 매개변수를 구성하려면 getHeader() 메서드로 키를 정의할 수 있습니다. 예:

const 원격 = _remote.init();

원격.getHeader().set("키", "값");

요청 URL​

요청 URL을 지정하려면 해당 HTTP 메서드 함수의 첫 번째 매개변수로 전달하면 됩니다:

const 원격 = _remote.init().asJSON()

원격.get("http://exemplo.com") // GET 호출용
원격.post("http://exemplo.com") // POST 호출용
원격.put("http://exemplo.com") // PUT 호출용
원격.delete("http://exemplo.com") // DELETE 호출용

요청에 데이터 추가​

요청 본문에 데이터를 추가해야 하는 경우 해당 메서드 함수의 두 번째 매개변수로 전달하면 됩니다:

const 원격 = _remote.init().asJSON();

원격.get("http://exemplo.com", _val.map().set("사용자_id", 1)); // GET 호출용
원격.post("http://exemplo.com", _val.map().set("사용자_id", 1)); // POST 호출용
원격.put("http://exemplo.com", _val.map().set("사용자_id", 1)); // PUT 호출용
원격.delete("http://exemplo.com", _val.map().set("사용자_id", 1)); // DELETE 호출용

응답​

요청 응답을 받은 후 json 또는 content 메서드를 사용하여 데이터를 읽을 수 있습니다:

const 원격 = _remote.init().asJSON();

const 응답 = 원격.post(
  "http://exemplo.com",
  _val.map().set("사용자_id", 1)
);

if (응답.ok()) {
  _log.info("JSON 응답", 응답.json());
} else {
  _log.info("실패, 상태: "+ 응답.statusCode(), 응답.content());
}

json() 함수가 포함된 응답에서는 Values로 제공된 배열 또는 객체를 얻고, content() 함수로는 원시 텍스트 콘텐츠 또는 HTML을 얻습니다. 수신된 상태 코드 번호는 statusCode()에 있으며, ok()는 상태 코드가 200에서 299 범위에 있으면 true인 부울 값을 반환합니다.

다운로드​

파일을 다운로드하려면 asBinary()와 함께 Remote를 사용하여 바이너리 전송임을 지정합니다.

다음은 완전한 서비스 예제입니다:

server/services/file-download.js
const 다운로드 = _remote.asBinary()
  .get('https://raw.githubusercontent.com/netuno-org/platform/main/docs/images/overview.png');

if (!다운로드.ok()) {
  _log.error(`파일 다운로드 상태: ${다운로드.statusCode()}\n${다운로드.toString()}`);
  _header.status(500);
  _out.json({결과: false, 오류: '파일-다운로드-실패'});
  _exec.stop();
}

const 파일 = 다운로드.file();
_log.info(`다운로드한 파일 이름: ${파일.name()}`);

파일.save(_app.file(`storage/filesystem/server/${파일.name()}`));
파일.save(_storage.filesystem("server", "기타.png").file());
파일.save(_os.file("/tmp/다운로드.png"));
_out.json({결과: true});

파일.save는 의도적으로 3번 사용되었습니다. _app.file, _storage, _os.file에 대해 더 알아보려면 파일 및 폴더 조작 튜토리얼을 참조하세요.

업로드​

multipart 형식의 폼으로 구조화된 파일을 전송하려면 asMultipartFormData()를 사용합니다.

다음은 완전한 서비스 예제입니다:

server/services/file-upload.js
const 파일 = _app.file("public/images/로고.png");

const 업로드 = _remote.asMultipartFormData()
  .post(
    'http://localhost:9000/services/file-receiver',
    _val.map()
      .set("파일", 파일)
  );

if (업로드.ok()) {
  _log.info(`업로드 성공: ${파일.name()}`);
  _out.json({결과: true});
} else {
  _log.error(`파일 업로드 상태: ${업로드.statusCode()}\n${업로드.toString()}`);
  _header.status(500);
  _out.json({결과: false, 오류: '파일-업로드-실패'});
}

위 예제에서는 파일이 다른 서비스로 전송됩니다. 파일을 수신하는 이 다른 서비스를 Netuno에서 구현하는 방법을 확인하세요:

server/services/file-receiver.js
const 파일 = _req.getFile("파일");
_log.info(`수신한 파일 이름: ${파일.name()}`);
파일.save(_storage.filesystem("server", "수신됨.png").file());
_out.json({결과: true});

결론​

Remote 리소스를 사용하면 외부 API를 통합하고 데이터를 내보내기, 가져오기 또는 동기화할 수 있습니다.

다른 기술로 구현된 서비스도 통합할 수 있어 다른 언어에서 제공하는 특정 작업을 수행할 수 있습니다.