응답 가져오기 - 범위가 지정됨, 전역

  • 릴리스 버전: Yokohama
  • 업데이트 날짜 2025년 01월 30일
  • 읽기19분

    • Fetch Response API는 새 Response 개체를 만들고 Fetch Request API 메서드에서 만든 응답 본문을 처리하기 위한 메서드를 제공합니다.

    Fetch Response API는 외부 웹 사이트에서 리소스를 가져오기 위한 다양한 작업을 제공하는 Fetch API 집합의 일부입니다. 전체 Fetch API 컬렉션에는 다음이 포함됩니다.

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

    응답 속성

    응답 API는 HTTP 응답에 대한 세부 정보를 반환하는 속성을 제공합니다. 이러한 속성을 사용하면 추가 처리를 위해 메타데이터( 예: 상태, 헤더, 유형) 및 응답 본문(본문)에 액세스할 수 있습니다. 이를 통해 요청의 성공 여부(확인)를 확인하고 반환된 데이터를 다양한 형식(예: JSON 또는 텍스트)으로 구문 분석할 수 있습니다. 이러한 속성은 클라이언트 측 애플리케이션에서 서버 응답을 확인하고 처리하는 데 중요합니다. 각 속성에 대한 자세한 설명은 문서를 참조하십시오 https://developer.mozilla.org/en-US/docs/Web/API/Response.

    표 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
});
    헤더 읽기 전용입니다. 응답과 연결된 헤더 객체입니다.

    데이터 유형: 헤더 객체

    		 
    const myRequest = new Request("flowers.jpg");
const myHeaders = myRequest.headers; // Headers {}
    ok 준비 전용입니다. 응답이 성공했는지 여부(200-299 범위의 상태)를 나타내는 플래그입니다.
    허용되는 값:
    • true: 응답이 성공했습니다.
    • false: 응답이 성공하지 못했습니다.

    데이터 유형: 부울

    		 
    const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest).then((response) => {
  console.log(response.ok); // returns true if the response returned successfully
  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
    리디렉션됨 읽기 전용입니다. 응답이 요청이 리디렉션된 결과인지 여부를 나타내는 플래그입니다.
    허용되는 값:
    • true: 요청이 리디렉션되었습니다.
    • false: 요청이 리디렉션되지 않았습니다.

    데이터 유형: 부울

    		 
    const myRequest = new Request("flowers.jpg");
const myCred = myRequest.redirect;
    상태 읽기 전용입니다. 응답의 HTTP 상태 코드입니다. 예를 들어 성공의 경우 200입니다.

    데이터 유형: 숫자

    		 
    const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => {
    console.log("response.status =", response.status); // response.status = 200
    return response.blob();
  })
  .then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
    statusText 읽기 전용입니다. response.status의 HTTP 상태 코드에 해당하는 상태 메시지입니다. 예를 들어 상태 코드 200의 경우 괜찮고, 100의 경우 계속, 404의 경우 찾을 수 없습니다.

    데이터 유형: 문자열

    		 
    const myRequest = new Request("flowers.jpg");

 // Log the HTTP status and status text
    console.log(`Status: ${response.status}`);
    console.log(`Status Text: ${response.statusText}`);
    
    // Check if the response is successful
    if (response.ok) {
      console.log("Request succeeded!");
    } else {
      console.log("Request failed.");
    }
  } catch (error) {
    console.error("Error fetching the URL:", error);
  }
}
    유형 읽기 전용입니다. 대응 유형입니다.
    허용되는 값:
    • basic: "Set-Cookie"를 제외한 모든 헤더가 노출된 정상적이고 동일한 원본 응답입니다.
    • cors: 유효한 교차 출처 요청에서 응답을 받았습니다. 특정 헤더와 본문에 액세스할 수 있습니다.
    • 오류: 네트워크 오류입니다. 오류를 설명하는 유용한 정보가 없습니다. 응답의 상태는 0이고 헤더는 비어 있으며 변경할 수 없습니다. 이것은 Response.error()에서 얻은 Response의 유형입니다.
    • opaque: 교차 출처 자원에 대한 "no-cors" 요청에 대한 응답입니다. 심각하게 제한됨.
    • opaqueredirect: 가져오기 요청이 redirect: "manual"로 이루어졌습니다. 응답의 상태는 0이고, 헤더는 비어 있고, 본문은 null이고, 트레일러는 비어 있습니다.

    데이터 유형: 문자열

    		 
    const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => {
    console.log("response.type =", response.type); // response.type = 'basic'
    return response.blob();
  })
  .then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
    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"

    응답 가져오기 - 응답(객체 본문, 객체 옵션)

    Response() 생성자를 사용하여 새 Response 객체를 만듭니다.

    표 2. 매개변수
    이름 유형 설명
    본문 객체 옵션입니다. 응답 본문을 정의하는 객체입니다.
    유효한 유형:
    • 어레이 버퍼
    • Blob
    • 데이터뷰
    • FormData
    • ReadableStream
    • 문자열
    • 문자열 리터럴
    • TypedArray
    • URLSearchParams

    기본값: null
    옵션 객체 옵션입니다. 응답에 적용할 사용자 지정 설정을 포함하는 options 객체 또는 빈 객체(기본값)입니다. 가능한 옵션은 다음과 같습니다.
    • headers: 응답에 추가하려는 모든 헤더로, 문자열 키/값 쌍의 개체 또는 개체 리터럴 내에 헤더 가져오기 - 범위 지정, 전역 포함됩니다(참조는 HTTP 헤더를 참조하세요). 기본적으로 비어 있습니다.
    • status: 응답의 상태 코드입니다. 기본값은 200입니다.
    • statusText: 상태 코드와 연결된 상태 메시지입니다(예: "확인"). 기본값은 ""입니다.

    이 예제에서는 생성자를 사용하여 새 Response 개체를 만들고, 새 Blob을 본문으로 전달하고, init 개체와 사용자 지정 status 및 statusText 옵션을 포함합니다.

    const myBlob = new Blob();
const myOptions = { status: 200, statusText: "Status message!" };
const myResponse = new Response(myBlob, myOptions);

    응답 가져오기 - arrayBuffer()

    ArrayBuffer로 해결되는 promise를 반환합니다.

    arrayBuffer() 메서드는 이미지, 오디오 파일 또는 처리해야 하는 기타 바이너리 파일과 같은 바이너리 데이터로 작업할 때 유용합니다.

    표 3. 매개변수
    이름 유형 설명
    없음
    표 4. 반환
    유형 설명
    객체 일반 원시 이진 데이터 버퍼를 나타내는 ArrayBuffer로 해결되는 약속입니다.
    표 5. 예외
    예외 설명
    DOMException - AbortError 요청이 중단되었음을 알리는 예외입니다.
    TypeError 다음 이유 중 하나로 인해 발생합니다.
    • 응답 본문이 교란되거나 잠겨 있습니다.
    • 본문 내용을 디코딩하는 동안 오류가 발생했습니다(예: Content-Encoding 헤더가 잘못되었기 때문에).
    범위 오류 연결된 ArrayBuffer를 생성하는 데 문제가 발생했습니다. 예를 들어 데이터 크기가 너무 큰 경우입니다.
    다음 예제 스크립트는 서버에서 이진 데이터를 가져오고 다음 단계를 사용하여 arrayBuffer() 메서드를 활용하는 동안 처리합니다.
    1. fetch(): 지정된 URL에서 자원을 가져옵니다.
    2. response.ok: 응답 상태가 200-299 범위인지 확인합니다.
    3. arrayBuffer(): 응답 본문을 읽고 일반 고정 길이 원시 이진 데이터 버퍼를 나타내는 ArrayBuffer로 변환합니다.
    4. Uint8Array: ArrayBuffer를 이진 데이터를 쉽게 조작할 수 있도록 형식화된 배열인 Uint8Array로 변환합니다.
    javascriptCopy code// Simple API to fetch binary data and process it using arrayBuffer()asyncfunctionfetchBinaryData(url) {
  try {
    // Fetch the resource from the provided URLconst response = awaitfetch(url);

    // Check if the response is successfulif (!response.ok) {
      thrownewError(`HTTP error! Status: ${response.status}`);
    }

    // Convert the response body to an ArrayBufferconst arrayBuffer = await response.arrayBuffer();

    // Process the ArrayBuffer (e.g., convert it to a typed array)const uint8Array = newUint8Array(arrayBuffer);

    // Return the processed datareturn uint8Array;
  } catch (error) {
    console.error("Error fetching or processing binary data:", error);
    throw error;
  }
}

// Example usageconst binaryDataUrl = 'https://example.com/path/to/binary/data';

fetchBinaryData(binaryDataUrl)
  .then((data) => {
    console.log("Binary data as Uint8Array:", data);
    // Further processing can be done here, e.g., rendering an image or playing audio
  })
  .catch((error) => {
    console.error("Failed to fetch binary data:", error);
  });

    응답 가져오기 - blob()

    Blob으로 해결되는 promise를 반환합니다.

    표 6. 매개변수
    이름 유형 설명
    없음
    표 7. 반환
    유형 설명
    객체 Blob으로 해결되는 promise입니다.
    표 8. 예외
    예외 설명
    DOMException - AbortError 요청이 중단되었음을 알리는 예외입니다.
    TypeError 다음 이유 중 하나로 인해 발생합니다.
    • 응답 본문이 교란되거나 잠겨 있습니다.
    • 본문 내용을 디코딩하는 동안 오류가 발생했습니다(예: Content-Encoding 헤더가 잘못되었기 때문에).
    다음 예제에서는 다음 단계를 사용하여 Fetch API와 함께 blob() 메서드를 사용하는 방법을 보여 줍니다. 이 사용 사례는 이미지 또는 기타 이진 콘텐츠(예: 비디오 또는 PDF)를 가져와 동적으로 표시하는 데 유용합니다.
    1. fetch(url): 지정된 URL에서 자원을 가져옵니다.
    2. response.blob(): 응답 본문을 이진 데이터를 나타내는 Blob 개체로 변환합니다.
    3. URL.createObjectURL(blob): DOM에서 사용할 수 있는 Blob에 대한 임시 URL을 생성합니다(예: 이미지 소스).
    4. DOM에 이미지 추가: 이미지 요소를 동적으로 만들고, Blob URL을 원본으로 설정하고, 문서 본문에 추가합니다.
    
async function fetchBlob(url) {
  try {
    // Fetch the resource from the provided URL
    const response = await fetch(url);

    // Check if the response is successful
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    // Convert the response body to a Blob
    const blob = await response.blob();

    // Create a URL for the Blob and log it
    const blobUrl = URL.createObjectURL(blob);
    console.log("Blob URL:", blobUrl);

    // For example, you can set it as the source of an image
    const img = document.createElement('img');
    img.src = blobUrl;
    img.alt = "Fetched Blob Image";
    document.body.appendChild(img);
  } catch (error) {
    console.error("Error fetching or processing blob:", error);
  }
}

// Example usage with an image URL
const imageUrl = 'https://via.placeholder.com/150';
fetchBlob(imageUrl);

    응답 가져오기 - bytes()

    Uint8Array로 해결되는 promise를 반환합니다.

    표 9. 매개변수
    이름 유형 설명
    없음
    표 10. 반환
    유형 설명
    객체 Uint8Array로 해결되는 promise입니다.
    표 11. 예외
    예외 설명
    DOMException- AbortError 요청이 중단되었습니다.
    TypeError 다음 이유 중 하나로 인해 발생합니다.
    • 응답 본문이 교란되거나 잠겨 있습니다.
    • 본문 내용을 디코딩하는 동안 오류가 발생했습니다(예: Content-Encoding 헤더가 잘못되었기 때문에).
    범위 오류 연결된 ArrayBuffer를 생성하는 데 문제가 발생했습니다. 예를 들어 데이터 크기가 너무 큰 경우입니다.

    다음 예제에서는 텍스트 파일을 가져오고 본문을 Uint8Array로 반환한 다음 이를 문자열로 디코딩하는 방법을 보여 줍니다.

    const response = await fetch("https://www.example.com/textfile.txt");
const textFile = await response.bytes();
const string = new TextDecoder().decode(textFile);
console.log(string);

    응답 가져오기 - formData()

    FormData 객체로 해결되는 promise를 반환합니다.

    표 12. 매개변수
    이름 유형 설명
    없음
    표 13. 반환
    유형 설명
    객체 FormData 객체로 해결되는 약속입니다.
    표 14. 예외
    예외 설명
    DOMException- AbortError 요청이 중단되었습니다.
    TypeError 다음 이유 중 하나로 인해 발생합니다.
    • 응답 본문이 교란되거나 잠겨 있습니다.
    • 본문 내용을 디코딩하는 동안 오류가 발생했습니다(예: Content-Encoding 헤더가 잘못되었기 때문에).
    다음 예시에서는 formData() 를 사용하여 다음 단계를 통해 양식 제출 응답을 처리하는 방법을 보여줍니다.
    1. 요청 본문: JSON.stringify() 를 사용하여 URL로 인코딩된 매개변수 대신 양식 데이터를 JSON으로 전송했습니다.
    2. Content-Type: 요청 본문 형식을 나타내기 위해 application/json 으로 설정합니다.
    // Example of using Response.formData()
async function fetchFormData(url) {
  try {
    // Make a POST request to fetch the form data
    const response = await fetch(url, {
      method: 'POST',
      body: JSON.stringify({
        name: 'John Doe',
        email: 'john.doe@example.com',
      }),
      headers: {
        'Content-Type': 'application/json',
      },
    });

    // Check if the response is successful
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    // Parse the response as FormData
    const formData = await response.formData();

    // Iterate through the FormData entries
    for (const [key, value] of formData.entries()) {
      console.log(`${key}: ${value}`);
    }
  } catch (error) {
    console.error("Error fetching or processing form data:", error);
  }
}

// Example usage
const formEndpoint = 'https://httpbin.org/post'; // Replace with your form endpoint
fetchFormData(formEndpoint);

    출력:

    name: John Doe
email: john.doe@example.com

    응답 가져오기 - json()

    본문 텍스트를 JSON으로 구문 분석한 결과로 확인되는 약속을 반환합니다.

    주:
    이 메서드의 이름에도 불구하고 json() 의 결과는 JSON이 아니라 JSON을 입력으로 사용하고 구문 분석하여 JavaScript 객체를 생성한 결과입니다.
    표 15. 매개변수
    이름 유형 설명
    없음
    표 16. 반환
    유형 설명
    객체 JavaScript 객체로 확인되는 promise입니다. 이 객체는 객체, 배열, 문자열, 숫자 등과 같이 JSON으로 표현할 수 있는 모든 것이 될 수 있습니다.
    표 17. 예외
    예외 설명
    DOMException- AbortError 요청이 중단되었습니다.
    TypeError 다음 이유 중 하나로 인해 발생합니다.
    • 응답 본문이 교란되거나 잠겨 있습니다.
    • 본문 내용을 디코딩하는 동안 오류가 발생했습니다(예: Content-Encoding 헤더가 잘못되었기 때문에).
    구문 오류 응답 본문을 JSON으로 구문 분석할 수 없습니다.
    다음 예제에서는 json() 을 사용하여 응답을 구성하는 방법을 보여 줍니다.
    1. fetch() 는 URL에 GET 요청을 합니다.
    2. response.ok 요청이 성공했는지 확인합니다(상태 코드 200–299).
    3. 성공하면 응답에서 JSON 데이터를 구문 분석하기 위해 response.json() 가 호출됩니다.
    4. 구문 분석된 데이터는 콘솔 API를 사용하여 시스템 로그에 기록됩니다. 요청 또는 구문 분석 중에 오류가 발생하면 catch되고 기록됩니다.
    fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error('Fetch error:', error));

    응답 가져오기 - text()

    응답 본문을 읽고 일반 문자열로 반환합니다. 응답은 항상 UTF-8을 사용하여 디코딩됩니다.

    text() 메서드는 HTML, JSON(수동으로 처리하려는 경우), XML 또는 일반 문자열로 처리되어야 하는 일반 텍스트 파일과 같은 텍스트 데이터가 포함된 응답에 유용합니다.

    표 18. 매개변수
    이름 유형 설명
    없음
    표 19. 반환
    유형 설명
    안 함 UTF-8로 인코딩된 문자열로 해결되는 약속입니다.
    표 20. 예외
    예외 설명
    DOMException- AbortError 요청이 중단되었습니다.
    TypeError 다음 이유 중 하나로 인해 발생합니다.
    • 응답 본문이 교란되거나 잠겨 있습니다.
    • 본문 내용을 디코딩하는 동안 오류가 발생했습니다(예: Content-Encoding 헤더가 잘못되었기 때문에).

    다음 예제는 서버가 Hello, world와 같은 일반 텍스트를 반환할 때 text()를 사용하는 간단한 방법을 보여줍니다. 샘플 응답입니다.

    const response = awaitfetch('https://example.com/text-endpoint');
const text = await response.text();
console.log(text); // Outputs: Hello, world! This is a sample response.

    출력:

    Hello, world! This is a sample response.