클라이언트 API 서버 엔드포인트 및 클라우드 흐름

$pages.ajax

이 개체는 $pages.ajax 사이트에서 서버 쪽 엔드포인트를 호출하는 데 사용하는 일반 HTTP 요청 메서드를 제공합니다. 클라이언트 스크립트에서 서버 논리, 클라우드 흐름 및 기타 사용자 지정 /_api/ 엔드포인트를 호출하는 데 사용합니다. 이 개체는 $pages.ajax 사이트에서 서버 쪽 엔드포인트를 호출하는 데 사용하는 일반 HTTP 요청 메서드 를 제공합니다. 클라이언트 스크립트에서 서버 논리, 클라우드 흐름 및 기타 사용자 지정 /_api/ 엔드포인트를 호출하는 데 사용합니다.

각 요청은 다음과 같이 자동으로 처리됩니다.

CSRF(교차 사이트 요청 위조) 토큰: 토큰이 처음 필요할 때 검색되고, 메모리에 캐시되고, 모든 요청의 헤더에 추가됩니다. 토큰을 검색하거나 전달할 필요가 없습니다.
자격 증명: 세션 쿠키는 모든 요청에 포함됩니다.
x-requested-with 헤더: 이 헤더는 모든 요청에 대해 XMLHttpRequest 설정됩니다.

request 메서드

지정된 URL에 대한 HTTP 요청을 만듭니다.

구문: $pages.ajax.request(options: object): Promise<AjaxResponse>
반환: AjaxResponse 개체로 확인되는 Promise입니다.

서버가 200-299 범위를 벗어난 상태 코드를 반환하거나 네트워크가 실패할 때 AjaxError 개체로 프라미스가 거부됩니다. 개체의 AbortSignal 취소 오류는 개체에 AjaxError 래핑되지 않습니다. 요청 취소를 참조하세요.

request 메서드 매개 변수

매개 변수는 options 다음 속성을 허용합니다.

재산	Type	필수	Description
`url`	string	예	상대 경로(예: `/_api/serverlogics/mylogic`절대 URL)
`method`	string	No	HTTP 메서드: `GET`, `POST`, `PUT`또는 `PATCHDELETE`. 이 값은 대/소문자를 구분하지 않습니다. 기본값은 `GET` 본문을 제공하지 않는 경우와 `POST` 본문을 제공할 때입니다.
`body`	object	No	요청 페이로드는 JSON으로 자동으로 직렬화됩니다. 본문은 을 비롯한 `GET`모든 메서드에 대해 전송됩니다. `GET` 본문이 있는 요청은 비표준이며 일부 HTTP 중개자가 이를 제거하므로 호출하는 API가 지원하는 경우에만 본문을 `GET` 사용합니다.
`params`	object	No	URL에 쿼리 문자열로 추가되는 키/값 쌍입니다. 값은 문자열로 변환됩니다. URL에 쿼리 문자열이 이미 포함되어 있으면 값이 추가됩니다.
`headers`	object	No	기본 헤더와 병합할 추가 헤더입니다. CSRF 헤더 또는 헤더를 재정의할 `x-requested-with` 수 없습니다.
`signal`	AbortSignal	No	진행 중인 요청을 취소하는 신호입니다. 요청 취소를 참조하세요.

AjaxResponse 개체

메서드는 request 다음 속성이 있는 개체로 확인됩니다.

재산	Type	Description
`data`	unknown	구문 분석된 응답 본문입니다.
`status`	number	HTTP 상태 코드입니다.
`ok`	부울	상태 코드가 200-299 범위인 경우 True입니다. 메서드가 `request` 다른 상태 코드에 대해 거부하므로 이 값은 메서드가 확인하는 모든 응답에 대해 true입니다.
`headers`	object	응답 헤더는 키/값 쌍으로 사용됩니다.

AjaxError 개체

메서드는 request 다음 속성이 있는 개체를 사용하여 거부합니다.

재산	Type	Description
`name`	string	값 `AjaxError`입니다. 다른 오류와 별도로 실패한 요청을 알리려면 이 속성을 확인합니다.
`message`	string	오류에 대한 설명입니다.
`status`	number	HTTP 상태 코드입니다. 값은 `0` 네트워크가 실패하고 응답을 받지 못하는 경우입니다.
`body`	unknown	서버가 반환될 때 구문 분석된 응답 본문입니다. 그렇지 않으면 null입니다.
`requestId`	string \| undefined	응답 헤더의 서버 쪽 요청 추적 ID입니다 `x-ms-request-id` . 문제를 보고할 때 이 값을 포함합니다.

요청 메서드 예제

다음 예제를 사용하여 요청 메서드를 사용하는 방법을 알아봅니다.

예시	Description
GET 요청을 사용하여 서버 논리 호출	GET 요청을 사용하여 쿼리 문자열 매개 변수를 서버 논리에 전달합니다.
POST 요청을 사용하여 서버 논리 호출	POST 요청을 사용하여 서버 논리에 요청 본문을 보냅니다.
클라우드 흐름 트리거	사이트에 등록된 클라우드 흐름을 트리거하고 흐름 응답을 처리합니다.
PUT 요청을 사용하여 리소스 업데이트	PUT 요청과 함께 요청 본문을 전송하여 서버 리소스를 업데이트합니다.
DELETE 요청을 사용하여 리소스 삭제	쿼리 문자열 매개 변수와 함께 DELETE 요청을 사용하여 서버 리소스를 삭제합니다.
오류 처리	상태를 `AjaxError` catch하고 해당 상태, 응답 본문 및 요청 ID를 기록합니다.
요청 취소	요청을 취소하는 `AbortSignal` 방법과 취소 오류가 반환되는 방법을 설명합니다.
고정 기간 후 요청 취소	최대 대기 시간 후에 요청을 취소하는 데 사용합니다 `AbortSignal.timeout` .
구성 요소가 제거될 때 요청 취소	`AbortController` 연결된 구성 요소가 제거될 때 요청을 취소하는 데 사용합니다.
이전 요청 취소	부실 응답이 순서대로 도착하지 않도록 교체를 시작하기 전에 미완성 요청을 취소합니다.

GET 요청을 사용하여 서버 논리 호출

이 예제에서는 쿼리 문자열 매개 변수를 서버 논리에 전달합니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const response = await $pages.ajax.request({
      method: 'GET',
      url: '/_api/serverlogics/getweather',
      params: { city: 'Seattle' }
    });
    console.log(response.data);
});

POST 요청을 사용하여 서버 논리 호출

이 예제에서는 서버 논리에 요청 본문을 보냅니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const response = await $pages.ajax.request({
      method: 'POST',
      url: '/_api/serverlogics/createorder',
      body: { productId: 'abc123', quantity: 2 }
    });
    console.log(response.data);
});

클라우드 흐름 트리거

Power Pages 디자인 스튜디오는 사이트에 흐름을 등록할 때 클라우드 흐름 URL을 생성합니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const response = await $pages.ajax.request({
      method: 'POST',
      url: '/_api/cloudflow/v1.0/trigger/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
      body: { Location: 'Seattle' }
    });

    // The data property is null when the flow has no Response action and returns 202 Accepted.
    // The data property contains the flow output when the flow has a Response action and returns 200 OK.
    if (response.data) {
      console.log(response.data);
    }
});

PUT 요청을 사용하여 리소스 업데이트

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.ajax.request({
      method: 'PUT',
      url: '/_api/serverlogics/updateprofile',
      body: { displayName: 'New Name' }
    });
});

DELETE 요청을 사용하여 리소스 삭제

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.ajax.request({
      method: 'DELETE',
      url: '/_api/serverlogics/deleteitem',
      params: { id: '99' }
    });
});

오류를 처리하십시오.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    try {
      const response = await $pages.ajax.request({
        method: 'POST',
        url: '/_api/serverlogics/createorder',
        body: { productId: 'abc123', quantity: 2 }
      });
      console.log('Order created:', response.data);
    } catch (err) {
      if (err.name === 'AjaxError') {
        console.error(`Request failed with status ${err.status}`);
        console.error('Response body:', err.body);
        // Provide err.requestId to support for server-side tracing.
        if (err.requestId) {
          console.error('Request ID:', err.requestId);
        }
      } else {
        throw err;
      }
    }
});

요청 취소

이 속성은 signalAbortSignal 개체를 허용합니다. 신호가 중단되면 진행 중인 요청이 취소되고 취소 오류로 약속이 거부됩니다. 이 오류는 AjaxError 개체에 래핑되지 않으며 해당 name 속성은 다음과 같습니다 CanceledError. 이 오류를 실패한 요청으로 처리하지 마세요.

고정 기간 후 요청 취소

이 메서드를 AbortSignal.timeout 사용하여 컨트롤러를 관리하지 않고 최대 대기 시간을 설정합니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    try {
      const response = await $pages.ajax.request({
        method: 'GET',
        url: '/_api/serverlogics/slowlogic',
        signal: AbortSignal.timeout(5000) // Cancel after 5 seconds.
      });
      console.log(response.data);
    } catch (err) {
      // A timeout is reported as a CanceledError. The underlying DOMException, which has
      // the name TimeoutError, is available on err.cause when you need to tell a timeout
      // apart from a manual cancellation.
      if (err.name === 'CanceledError') {
        if (err.cause?.name === 'TimeoutError') {
          console.warn('Request timed out.');
        } else {
          console.warn('Request was canceled.');
        }
      } else {
        // Handle server and network failures.
        console.error(err);
      }
    }
});

구성 요소가 제거될 때 요청 취소

요청이 구성 요소의 수명 주기에 연결된 경우 코드가 더 이상 존재하지 않는 구성 요소를 업데이트하지 않도록 구성 요소가 제거될 때 요청을 취소합니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const controller = new AbortController();

    $pages.ajax.request({
      method: 'GET',
      url: '/_api/serverlogics/getdata',
      signal: controller.signal
    })
    .then(response => {
      // Update the UI with response.data.
    })
    .catch(err => {
      if (err.name !== 'CanceledError') {
        // Handle actual errors and ignore intentional cancellations.
        console.error(err);
      }
    });

    // Call this function from your cleanup logic, such as when the component
    // is removed from the page.
    const dispose = () => {
        controller.abort();
    };
});

이전 요청 취소

검색 상자에 입력하는 경우와 같이 이전 요청이 완료되기 전에 누군가가 새 요청을 트리거하는 경우 부실 응답이 순서대로 도착하지 않도록 이전 요청을 취소합니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let controller = null;

    async function search(query) {
      if (controller) {
        controller.abort(); // Cancel the previous request.
      }
      controller = new AbortController();

      try {
        const response = await $pages.ajax.request({
          method: 'GET',
          url: '/_api/serverlogics/search',
          params: { q: query },
          signal: controller.signal
        });
        console.log('Results:', response.data);
      } catch (err) {
        if (err.name !== 'CanceledError') {
          console.error(err);
        }
      }
    }

    // Run a search each time someone types in the search box.
    const searchBox = document.querySelector('#searchBox');

    if (searchBox) {
        searchBox.addEventListener('input', (e) => search(e.target.value));
    }
});

피드백

이 페이지가 도움이 되었나요?

2026-09-21 에 마지막으로 업데이트됨