요청 가져오기 - 범위가 지정됨, 전역

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 24분

    • Fetch Request API에는 애플리케이션이 서버에서 JSON, 텍스트 또는 이진 데이터와 같은 리소스를 비동기적으로 요청하고 응답을 처리할 수 있도록 Request 개체를 생성하거나 검색하는 메서드가 포함되어 있습니다. 이 API는 GET, POST, PUT, DELETE 등의 다양한 HTTP 메서드를 지원합니다.

    이 API는 외부 웹 사이트에서 자원을 가져오기 위한 다양한 작업을 제공하는 Fetch API 세트의 일부입니다. 전체 Fetch API 컬렉션에는 다음이 포함됩니다.

    가져오기 작업을 지원하기 위해 시스템 속성 glide.hosts.allowlist를 사용하면 가져오기 메서드가 액세스할 수 있는 호스트를 제어할 수 있습니다. RestMessageV2와 같은 HTTP API 및 위에서 언급한 API에 적용됩니다. glide.hosts.allowlist에 대한 자세한 내용은 문서를 참조하십시오Available system properties.

    요청 속성

    Fetch Request API는 HTTP 요청에 대한 자세한 정보를 제공하는 여러 읽기 전용 속성을 지원합니다. 여기에는 url (요청의 URL), method (HTTP 메서드), headers (연결된 헤더) 및 body (스트림으로서의 요청 본문)가 포함됩니다. 다른 속성으로는 캐싱, 자격 증명 및 참조자에 대한 설정이 있습니다. 이러한 속성은 읽기 전용이므로 요청이 생성된 후에는 액세스할 수 있지만 수정할 수는 없습니다. 각 속성에 대한 자세한 내용은 문서를 참조하십시오 https://developer.mozilla.org/en-US/docs/Web/API/Request.

    표 1. 요청 속성
    속성 이름 설명 예제
    본문 준비 전용 속성입니다. 요청에 추가된 본문 내용과 함께 읽을 수 있는 바이트 데이터 스트림을 포함합니다.

    데이터 형식/값: ReadableStream 또는 null입니다.

    		 
    const request = new Request("/myEndpoint", {
  method: "POST",
  body: "Hello world",
});

request.body; // ReadableStream
    body사용됨 준비 전용 속성입니다. 요청 본문을 아직 읽지 않았는지 여부를 나타내는 플래그입니다.
    수락된 값:
    • true: 요청 본문을 읽었습니다.
    • false: 요청 본문을 읽지 않았습니다.

    데이터 유형: 부울

    		 
    const request = new Request("/myEndpoint", {
  method: "POST",
  body: "Hello world",
});

request.bodyUsed; // false

request.text().then((bodyAsText) => {
  console.log(request.bodyUsed); // true
});
    캐시 준비 전용 속성입니다. 요청이 브라우저의 HTTP 캐시와 상호 작용하는 방식을 제어하는 요청의 캐시 모드를 포함합니다.
    허용되는 값:
    • 기본값: 브라우저는 HTTP 캐시에서 일치하는 요청을 찾습니다.
      • 일치하는 항목이 있고 최신 상태인 경우 캐시에서 반환됩니다.
      • 일치하는 항목이 있지만 오래된 경우 브라우저는 원격 서버에 조건부 요청을 합니다. 서버에서 리소스가 변경되지 않았음을 나타내면 캐시에서 반환됩니다. 그렇지 않으면 리소스가 서버에서 다운로드되고 캐시가 업데이트됩니다.
      • 일치하는 항목이 없으면 브라우저는 일반 요청을 하고 다운로드한 리소스로 캐시를 업데이트합니다.
    • force-cache: 브라우저는 HTTP 캐시에서 일치하는 요청을 찾습니다.
      • 일치 항목(fresh/stale)이 있으면 캐시에서 반환됩니다.
      • 일치하는 항목이 없으면 브라우저는 일반 요청을 하고 다운로드한 리소스로 캐시를 업데이트합니다.
    • no-cache: 브라우저가 HTTP 캐시에서 일치하는 요청을 찾습니다.
      • 일치하는 항목(fresh, stale)이 있는 경우 브라우저는 원격 서버에 조건부 요청을 합니다. 서버에서 리소스가 변경되지 않았음을 나타내면 캐시에서 반환됩니다. 그렇지 않으면 리소스가 서버에서 다운로드되고 캐시가 업데이트됩니다.
      • 일치하는 항목이 없으면 브라우저는 일반 요청을 하고 다운로드한 리소스로 캐시를 업데이트합니다.
    • no-store : 브라우저는 캐시를 먼저 찾지 않고 원격 서버에서 리소스를 가져오고 다운로드 한 리소스로 캐시를 업데이트하지 않습니다.
    • only-if-cached: 브라우저는 HTTP 캐시에서 일치하는 요청을 찾습니다.
      • 일치 항목(fresh/stale)이 있으면 캐시에서 반환됩니다.
      • 일치하는 항목이 없으면 브라우저는 504 게이트웨이 시간 초과 상태로 응답합니다.

      only-if-cached 모드는 요청의 모드가 동일 원본인 경우에만 사용할 수 있습니다. 캐시된 리디렉션은 요청의 리디렉션 속성이 follow 이고 리디렉션이 동일 원본 모드를 위반하지 않는 경우 따릅니다.

    • reload: 브라우저가 캐시를 먼저 확인하지 않고 원격 서버에서 리소스를 가져온 다음 다운로드한 리소스로 캐시를 업데이트합니다.

    데이터 유형: 문자열

    		 
    // Download a resource with cache busting, to bypass the cache
// completely.
fetch("some.json", { cache: "no-store" }).then((response) => {
  /* consume the response */
});

// Download a resource with cache busting, but update the HTTP
// cache with the downloaded resource.
fetch("some.json", { cache: "reload" }).then((response) => {
  /* consume the response */
});

// Download a resource with cache busting when dealing with a
// properly configured server that will send the correct ETag
// and Date headers and properly handle If-Modified-Since and
// If-None-Match request headers, therefore we can rely on the
// validation to guarantee a fresh response.
fetch("some.json", { cache: "no-cache" }).then((response) => {
  /* consume the response */
});

// Download a resource with economics in mind! Prefer a cached
// albeit stale response to conserve as much bandwidth as possible.
fetch("some.json", { cache: "force-cache" }).then((response) => {
  /* consume the response */
});

// Naive stale-while-revalidate client-level implementation.
// Prefer a cached albeit stale response; but update if it's too old.
// AbortController and signal to allow better memory cleaning.
// In reality; this would be a function that takes a path and a
// reference to the controller since it would need to change the value
let controller = new AbortController();
fetch("some.json", {
  cache: "only-if-cached",
  mode: "same-origin",
  signal: controller.signal,
})
  .catch((e) =>
    e instanceof TypeError && e.message === "Failed to fetch"
      ? { status: 504 } // Workaround for chrome; which fails with a TypeError
      : Promise.reject(e),
  )
  .then((res) => {
    if (res.status === 504) {
      controller.abort();
      controller = new AbortController();
      return fetch("some.json", {
        cache: "force-cache",
        mode: "same-origin",
        signal: controller.signal,
      });
    }
    const date = res.headers.get("date"),
      dt = date ? new Date(date).getTime() : 0;
    if (dt < Date.now() - 86_400_000) {
      // if older than 24 hours
      controller.abort();
      controller = new AbortController();
      return fetch("some.json", {
        cache: "reload",
        mode: "same-origin",
        signal: controller.signal,
      });
    }

    // Other possible conditions
    if (dt < Date.now() - 300_000)
      // If it's older than 5 minutes
      fetch("some.json", { cache: "no-cache", mode: "same-origin" }); // no cancellation or return value.
    return res;
  })
  .then((response) => {
    /* consume the (possibly stale) response */
  })
  .catch((error) => {
    /* Can be an AbortError/DOMException or a TypeError */
  });
    자격 증명 읽기 전용입니다. 자격 증명 옵션의 Request() 생성자에 지정된 값을 반영합니다. 자격 증명은 쿠키, TLS 클라이언트 인증서 또는 사용자 이름과 암호가 포함된 인증 헤더입니다.
    허용되는 값:
    • include: 교차 오리진 요청에 대해서도 항상 자격 증명을 포함합니다.
    • 생략: 요청에 자격 증명을 보내거나 응답에 자격 증명을 포함하지 않습니다.
    • same-origin: same-origin 요청에 대한 자격 증명만 보내고 포함합니다.

    데이터 유형: 문자열

    		 
    const request = new Request("flowers.jpg");
const request = request.request; // returns "same-origin" by default
    대상 읽기 전용입니다. 요청되는 콘텐츠의 유형을 설명하는 문자열을 반환합니다.
    허용되는 값:
    • audio: 대상은 오디오 데이터입니다.
    • audioworklet: 대상은 오디오 worklet에서 사용하기 위해 가져오는 데이터입니다.
    • document: 대상이 HTML 또는 XML 문서입니다.
    • embed: taget은 포함된 콘텐츠입니다.
    • fencedframe: 타겟은 펜스가 있는 프레임입니다.
    • font: 대상이 글꼴입니다.
    • frame: 대상은 프레임입니다.
    • iframe: 대상이 iframe입니다.
    • image: 대상은 이미지입니다.
    • json: 대상이 JSON 파일입니다.
    • manifest: 대상이 매니페스트입니다.
    • object: 대상은 개체입니다.
    • paintworklet : 대상은 페인트 워크릿입니다.
    • 보고서: 대상이 보고서입니다.
    • 스크립트: 대상이 스크립트입니다.
    • sharedworker: 대상이 공유 작업자입니다.
    • style: 대상은 스타일입니다.
    • track : 대상은 HTML <track>입니다.
    • 비디오: 대상은 비디오 데이터입니다.
    • worker: 대상이 작업자입니다.
    • xslt : 대상은 XSLT 변환입니다.

    데이터 유형: 문자열

    		 
    fetch('https://example.com/image.jpg', {
  destination: 'image'
})
  .then(response => response.blob())
  .then(blob => {
    console.log('Image fetched successfully', blob);
  })
  .catch(error => console.error('Error:', error));
    헤더 읽기 전용입니다. 요청과 연결된 헤더 개체입니다.

    데이터 유형: 헤더 객체

    		 
    const myRequest = new Request("flowers.jpg");
const myHeaders = myRequest.headers; // Headers {}
    무결성 읽기 전용입니다. 요청의 하위 자원 무결성 값입니다.

    값: 요청을 생성할 때 인수로 options.integrity 전달된 값입니다. 무결성이 지정되지 않은 경우 속성은 ''를 반환합니다.

    		 
    const myRequest = new Request("flowers.jpg", {
  integrity: "sha256-abc123",
});
console.log(myRequest.integrity); // "sha256-abc123"
    isHistoryNavigation 읽기 전용입니다. 요청이 이력 탐색인지 여부를 나타내는 부울입니다.
    허용되는 값:
    • true: 요청이 이력 탐색입니다.
    • false: 요청이 이력 탐색이 아닙니다.

    데이터 유형: 부울

    		 
    self.addEventListener("request", (event) => {
  // ...

  if (event.request.isHistoryNavigation) {
    event.respondWith(
      caches.match(event.request).then((response) => {
        if (response !== undefined) {
          return response;
        } else {
          return fetch(event.request).then((response) => {
            let responseClone = response.clone();

            caches.open("v1").then((cache) => {
              cache.put(event.request, responseClone);
            });

            return response;
          });
        }
      }),
    );
  }

  // ...
});
    연결 유지 읽기 전용입니다. 요청의 연결 유지 설정(true 또는 false)입니다. 무결성 값이 요청에 전달되지 않은 경우 빈 문자열을 반환합니다.
    허용되는 값:
    • true: 브라우저가 시작된 페이지가 요청이 완료되기 전에 언로드되는 경우 연결된 요청을 활성 상태로 유지합니다.
    • false: 요청이 완료되기 전에 시작된 페이지가 언로드되는 경우 브라우저는 연결된 요청을 활성 상태로 유지하지 않습니다.

    데이터 유형: 부울

    		 
    const options = {
  keepalive: true,
};

const myRequest = new Request("flowers.jpg", options);
let myKeepAlive = myRequest.keepalive; // true
    방법 읽기 전용입니다. 요청 방법(GET, POST 등)

    데이터 유형: 문자열

    		 
    const myRequest = new Request("flowers.jpg");
const myMethod = myRequest.method; // GET
    모드 읽기 전용입니다. 요청의 모드입니다. 교차 원본 요청이 유효한 응답으로 이어지는지 여부와 응답의 어떤 속성을 읽을 수 있는지 결정하는 데 사용됩니다.
    허용되는 값:
    • cors: 요청이 교차 출처인 경우 CORS(Cross-Origin Resource Sharing) 메커니즘을 사용합니다.
    • navigate: 탐색을 지원하는 모드입니다. navigate 값은 HTML 탐색에서만 사용할 수 있습니다. 탐색 요청은 문서 사이를 탐색하는 동안에만 생성됩니다.
    • no-cors: 원본 간 요청에 대해 CORS를 사용하지 않도록 설정합니다. 응답이 불투명하므로 헤더와 본문을 JavaScript에서 사용할 수 없습니다.
    • same-origin: 교차 출처 요청을 허용하지 않습니다. 이 모드가 설정된 다른 원본에 대한 요청이 수행되면 결과는 오류입니다.

    요청은 다양한 방법으로 시작될 수 있으며 요청 모드는 시작된 특정 방법에 따라 다릅니다. 예를 들어 Request() 생성자를 사용하여 Request 개체를 만들면 해당 Request에 대한 mode 속성 값이 cors로 설정됩니다. 그러나 Request() 이외의 방법으로 생성된 요청의 경우 생성자, no-cors는 일반적으로 모드로 사용됩니다. 예를 들어 요청이 태그에서 시작되는 포함된 리소스의 경우 CrossOrigin 특성이 없는 한 대부분의 경우 요청은 no-CORS 모드(즉, OR) <link> 를 사용하여 이루어집니다 <script> elements (except when used with modules), or <img>, <audio>,<video>, <object>, <embed>, or <iframe> elements.

    데이터 유형: 문자열

    		 
    const myRequest = new Request("flowers.jpg");
const myMode = myRequest.mode; // returns "cors" by default
    redirect 읽기 전용입니다. 리디렉션을 처리하는 방법에 대한 모드입니다.
    유효한 값은 다음과 같습니다.
    • 오류
    • 뒤따르다
    • 수동

    데이터 유형: 문자열

    기본값: 팔로우

    		 
    const myRequest = new Request("flowers.jpg");
const myCred = myRequest.redirect;
    참조자 읽기 전용입니다. 요청의 참조자(예: 클라이언트, 참조자 없음 또는 URL)입니다. no-referrer 값은 빈 문자열을 반환합니다.

    데이터 유형: 문자열

    		 
    const myRequest = new Request("flowers.jpg");
const myReferrer = myRequest.referrer; // returns "about:client" by default
    리퍼러정책 읽기 전용입니다. 요청과 함께 Referrer 헤더에 전송되는 레퍼러 정보를 제어하는 레퍼러 정책입니다.

    데이터 유형: 문자열

    		 
    const myRequest = new Request("flowers.jpg");
const myReferrer = myRequest.referrerPolicy; // returns "" by default
    신호 읽기 전용입니다. AbortSignal을 요청과 연결합니다.

    데이터 유형: 문자열

    		 
    // Create a new abort controller
const controller = new AbortController();

// Create a request with this controller's AbortSignal object
const req = new Request("/", { signal: controller.signal });

// Add an event handler logging a message in case of abort
req.signal.addEventListener("abort", () => {
  console.log("abort");
});

// In case of abort, log the AbortSignal reason, if any
fetch(req).catch(() => {
  if (req.signal.aborted) {
    if (req.signal.reason) {
      console.log(`Request aborted with reason: ${req.signal.reason}`);
    } else {
      console.log("Request aborted but no reason was given.");
    }
  } else {
    console.log("Request not aborted, but terminated abnormally.");
  }
});

// Actually abort the request
controller.abort();
    URL 읽기 전용입니다. 요청의 URL입니다.

    데이터 유형: 문자열

    		 
    const myRequest = new Request("flowers.jpg");
const myURL = myRequest.url; // "https://github.com/mdn/dom-examples/tree/main/fetch/fetch-request/flowers.jpg"

    요청 가져오기 - Request()

    새 요청 객체를 작성합니다. 선택적으로 URL 또는 객체 자원에서 Request 객체를 생성합니다.

    표 2. 매개변수
    이름 유형 설명
    입력 문자열 또는 객체 옵션입니다. 검색할 자원입니다.

    유효한 값은 다음과 같습니다.

    • 가져올 자원의 URL을 포함하는 문자열입니다. API는 http://user.password.example.com 와 같은 자격 증명이 포함된 URL을 허용하지 않습니다. URL을 구문 분석할 수 없는 경우 예외가 발생합니다.
    • 기존 Request 개체의 복사본을 효과적으로 만드는 Request 개체입니다. 개체 구조는 Request 클래스에 의해 결정됩니다.
      주:
      생성자가 예외를 throw할 가능성을 줄이면서 보안을 유지하기 위해 다음 동작 업데이트를 확인합니다.
      • 이 개체가 생성자 호출의 다른 원본에 있는 경우 Request.referrer 속성이 제거됩니다.
      • 이 개체에 navigate의 Request.mode 속성이 있는 경우 모드 값은 same-origin으로 변환됩니다.
    옵션 객체 옵션입니다. RequestInit 가져오기 - 범위가 지정됨, 전역 요청에 적용할 사용자 지정 설정을 포함하는 객체입니다. 기존 요청에서 새 요청을 생성하는 경우 새 요청에 설정된 옵션이 원래 요청의 해당 옵션을 재정의합니다.

    기본값: 모든 속성의 기본값을 반환합니다.

    다음 예제에서는 Request() 생성자를 사용하여 새 Request 개체를 만드는 방법을 보여 줍니다.

    var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");

    다음 예제에서는 input 매개 변수를 사용하여 URL 또는 개체를 검색하는 새 Request 개체를 만드는 방법을 보여 줍니다.

    var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => response.blob())
  .then((response) => {
    var objectURL = URL.createObjectURL(response);
    myImage.src = objectURL;
  });

    다음 예제에서는 개체 리터럴을 사용하여 헤더 옵션이 있는 새 Request 개체를 만드는 방법을 보여 줍니다.

    var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");

var options = {
  headers: {
    "Cache-Control": "max-age=60480",
  },
};

    요청 가져오기 - arrayBuffer()

    요청 본문을 읽고 arrayBuffer로 해결되는 promise로 반환합니다.

    표 3. 매개변수
    이름 유형 설명
    없음
    표 4. 반환
    유형 설명
    약속 arrayBuffer로 해결되는 약속입니다.

    다음은 arrayBuffer() 메서드를 사용하여 새로운 요청을 생성하는 방법입니다.

    var myArray = new Uint8Array(10);

var request = new Request("/myEndpoint", {
  method: "POST",
  body: myArray,
});

request.arrayBuffer().then((buffer) => {
  // perform an action with the buffer sent in the request
});

    가져오기 요청 - blob()

    요청 본문을 읽고 Blob으로 해결되는 promise로 반환합니다.

    표 5. 매개변수
    이름 유형 설명
    없음
    표 6. 반환
    유형 설명
    객체 Blob으로 해결되는 promise입니다.

    다음 예제에서는 blob() 메서드를 사용하여 요청을 구성하는 방법을 보여 줍니다.

    var obj = { hello: "world" };
var myBlob = new Blob([JSON.stringify(obj, null, 2)], {
  type: "application/json",
});

var request = new Request("/myEndpoint", {
  method: "POST",
  body: myBlob,
});

request.blob().then((myBlob) => {
  // do something with the blob sent in the request
});

    요청 가져오기 - bytes()

    요청 본문을 읽고 Uint8Array로 해결되는 promise로 반환합니다.

    표 7. 매개변수
    이름 유형 설명
    없음
    표 8. 반환
    유형 설명
    객체 Uint8Array로 해결되는 promise입니다.

    다음은 bytes() 메서드를 사용하여 새 요청을 만드는 방법을 보여줍니다.

    var myArray = new Uint8Array(10);

var request = new Request("/myEndpoint", {
  method: "POST",
  body: myArray,
});

request.bytes().then((buffer) => {
  // do something with the buffer sent in the request
});

    요청 가져오기 - clone()

    현재 Request 객체의 복사본을 만듭니다.

    표 9. 매개변수
    이름 유형 설명
    없음
    표 10. 반환
    유형 설명
    요청 clone()이 호출된 요청의 정확한 복사본인 Request 객체입니다. clone()은 요청 본문이 이미 사용된 경우 오류를 발생시킵니다. 요청을 수정하려면 생성자를 요청 가져오기 - Request() 사용합니다.

    다음 예제에서는 request() 를 사용하여 새 요청을 만든 다음 clone()을 사용하여 복사하는 방법을 보여 줍니다.

    var myRequest = new Request("flowers.jpg");
var newRequest = myRequest.clone(); // a copy of the request is now stored in newRequest

    요청 가져오기 - formData()

    요청 본문을 읽고 FormData 객체로 해결되는 promise로 반환합니다.

    표 11. 매개변수
    이름 유형 설명
    없음
    표 12. 반환
    유형 설명
    없음 FormData 객체로 해결되는 Promise입니다.

    다음 예제에서는 request() 를 사용하여 새 요청을 만든 다음 formData() 메서드로 이를 해결하여 FormData 객체로 확인하는 방법을 보여 줍니다.

    var formData = new FormData();
var fileField = document.querySelector('input[type="file"]');

formData.append("username", "abc123");
formData.append("avatar", fileField.files[0]);

var request = new Request("/myEndpoint", {
  method: "POST",
  body: formData,
});

request.formData().then((data) => {
  // do something with the formdata sent in the request
});

    요청 가져오기 - json()

    요청 본문을 읽고, 컨텐츠를 JSON으로 구문 분석하고, 구문 분석된 결과로 해결되는 promise를 반환합니다.

    표 13. 매개변수
    이름 유형 설명
    없음
    표 14. 반환
    유형 설명
    객체 JavaScript 객체로 확인되는 promise(비동기 작업 및 그 결과 값의 최종 완료 또는 실패)입니다. 이 객체는 JSON으로 표현할 수 있는 모든 것(객체, 배열, 문자열, 숫자 등)이 될 수 있습니다.

    다음 예제에서는 request( )를 사용한 다음 json() 을 사용하여 새 요청을 생성하여 요청을 구문 분석하고 JSON 객체로 반환하는 방법을 보여줍니다.

    var obj = { hello: "world" };

var request = new Request("/myEndpoint", {
  method: "POST",
  body: JSON.stringify(obj),
});

request.json().then((data) => {
  // process the data sent in the request
});

    요청 가져오기 - text()

    요청 본문을 읽고 UTF-8을 사용하여 디코딩된 문자열로 해결되는 promise로 반환합니다.

    표 15. 매개변수
    이름 유형 설명
    없음
    표 16. 반환
    유형 설명
    없음 UTF-8 형식의 문자열로 해결되는 약속입니다.

    이 예제에서는 text()를 호출하는 방법을 보여 줍니다.

    var text = "Hello world";

var request = new Request("/myEndpoint", {
  method: "POST",
  body: text,
});

request.text().then((text) => {
  // process the data sent in the request
});