Vercel API로 관리

Table of Contents

Vercel REST API를 이용한 Edge 설정 관리
Edge 설정 생성하기
Edge 설정 항목 업데이트하기
- Edge 설정 PATCH 요청 실패
모든 항목 읽기
메타데이터 읽기
모든 Edge 설정 목록 보기
Edge 설정 엔드포인트로 요청하기

Vercel REST API를 이용한 Edge 설정 관리

Vercel REST API를 사용하여 Edge 설정을 생성하고 업데이트하는 방법을 배우세요. 또한 Vercel REST API로 Edge 설정에 저장된 데이터를 읽을 수 있습니다.

Edge 설정을 생성하고 업데이트하는 작업에만 Vercel REST API를 사용하는 것이 좋습니다. 데이터를 읽는 작업(자주 수행해야 함)에는 SDK 사용을 강력히 권장합니다.

Edge 설정에 대한 업데이트는 전 세계적으로 전파되는 데 몇 초가 걸릴 수 있으므로, 즉시 Edge 설정 API 엔드포인트에서 사용할 수 없을 수 있습니다. 그러나 Vercel REST API에서 Edge 설정 데이터를 가져오면 항상 설정의 최신 버전이 반환됩니다. 요청은 Vercel의 최적화를 받지 않으며, 응답은 Vercel의 Edge 네트워크를 통해 제공되지 않습니다.

또한 API를 통해 Edge 설정에 대한 메타데이터를 요청할 수 있습니다.

이 섹션에서는 Vercel REST API를 사용하여 Edge 설정을 업데이트하고, 메타데이터에 대해 읽고, Edge 설정의 내용을 읽는 방법을 보여줍니다. Edge 설정과 관련된 다른 Vercel REST API 기능에 대해 알아보려면 API 사양 참조를 읽어보세요.

Edge 설정 생성하기

Vercel REST API를 사용하여 Edge 설정을 생성하려면, API 엔드포인트의 edge-config 경로로 POST 요청을 보내세요. URL은 다음과 같아야 합니다.

'https://api.vercel.com/v1/edge-config';

요청 본문은 "slug"를 키로 하고 원하는 Edge 설정의 이름을 값으로 하는 JSON 객체여야 합니다.

이름은 알파벳 문자, "_" 및 "-"만 포함할 수 있으며, 32자를 초과할 수 없습니다.

아래 예시를 참조하세요.

try {
  const createEdgeConfig = await fetch(
    'https://api.vercel.com/v1/edge-config',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${your_vercel_api_token_here}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        slug: 'your_edge_config_name_here',
      }),
    },
  );
  const result = await createEdgeConfig.json();
  console.log(result);
} catch (error) {
  console.log(error);
}

성공하면 다음과 비슷한 JSON 응답을 받게 됩니다.

{
  "createdAt": 1234567890123,
  "updatedAt": 1234567890123,
  "slug": "your_edge_config_slug_here",
  "id": "your_edge_config_id_here",
  "digest": "abc123efg456hij789",
  "sizeInBytes": 2,
  "itemCount": 0,
  "ownerId": "your_id_here"
}

위 예시는 Hobby 계정에 범위가 지정된 Edge 설정을 생성합니다. Edge 설정을 Vercel 팀에 범위를 지정하려면:

적절한 Vercel 팀에 범위가 지정된 Vercel REST API 접근 토큰을 생성하세요.
POST 요청에 ?teamId 쿼리 매개변수를 추가하세요. 그 값으로 팀의 ID를 설정하며, Vercel의 팀 대시보드의 설정 탭에서 찾을 수 있습니다.
?teamId 쿼리 매개변수를 사용하여 Edge 설정을 생성한 경우 "ownerId" 키의 값은 Vercel 팀의 ID가 됩니다.

Edge 설정 항목 업데이트하기

Edge 설정에 항목을 추가하거나 항목을 업데이트하려면, edge-config 엔드포인트로 PATCH 요청을 보내고 끝에 /your_edge_config_id_here/items를 추가하세요.

팀에 범위가 지정된 Edge 설정을 요청하는 경우, 엔드포인트 끝에 ?teamId=를 추가하고 = 기호 뒤에 Vercel 팀의 ID를 붙입니다.

URL은 다음과 같아야 합니다.

'https://api.vercel.com/v1/edge-config/your_edge_config_id_here/items?teamId=your_team_id_here';

요청 본문은 "items" 배열을 포함하는 JSON 객체여야 합니다. "items" 배열은 Edge 설정에 하려는 변경을 설명하는 객체를 포함해야 합니다. 다음 표는 이 객체들의 유효한 키와 값을 개요합니다.

속성	설명	유효한 값
"operation"	Edge 설정에 하려는 변경	"create", "update", "upsert", "delete"
"key"	Edge 설정에 추가하거나 업데이트하려는 키 이름	알파벳 문자, "_" 및 "-"만 포함하는 문자열. 최대 256자.
"value"	키에 할당하려는 값	문자열, JSON 객체, null 객체, 숫자 및 이전 네 가지 유형의 배열

다음 예시는 "example_key_1" 키를 "example_value_1" 값으로 생성한 다음, "example_key_2" 키를 "new_value"로 업데이트하는 요청 본문을 보여줍니다.

{
  "items": [
    {
      "operation": "create",
      "key": "example_key_1",
      "value": "example_value_1"
    },
    {
      "operation": "update",
      "key": "example_key_2",
      "value": "new_value"
    }
  ]
}

위 요청 본문을 Edge 설정에 보내는 API 호출은 다음과 같습니다.

try {
  const updateEdgeConfig = await fetch(
    'https://api.vercel.com/v1/edge-config/\
        your_edge_config_id_here/items',
    {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${your_vercel_api_token_here}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        items: [
          {
            operation: 'create',
            key: 'example_key_1',
            value: 'example_value_1',
          },
          {
            operation: 'update',
            key: 'example_key_2',
            value: 'new_value',
          },
        ],
      }),
    },
  );
  const result = await updateEdgeConfig.json();
  console.log(result);
} catch (error) {
  console.log(error);
}

성공적인 요청은 {"status":"ok"} 응답을 받게 됩니다.

Edge 설정 PATCH 요청 실패

PATCH 요청 본문의 "items" 배열에 있는 작업 중 하나라도 실패하면 전체 요청이 실패합니다. 실패한 요청은 요청 실패 이유에 대한 정보를 포함하는 객체를 가진 "error" 속성을 포함하는 응답 JSON 객체를 받게 됩니다.

예를 들어:

{
  "error": {
    "code": "forbidden",
    "message": "요청에 인증 토큰이 누락되었습니다",
    "missingToken": true
  }
}

이 예시에서는 인증 토큰이 누락되어 요청이 거부되었음을 나타내는 오류 메시지를 보여줍니다.

모든 항목 읽기

Edge 설정에서 항목을 읽을 때 Vercel REST API 사용은 권장하지 않습니다. 대신 SDK를 사용하거나 Edge 설정 엔드포인트로 Edge 설정 데이터를 가져와야 합니다.

그러나 API를 통해 Edge 설정을 읽어야 하는 경우 edge-config 엔드포인트로 GET 요청을 하여 수행할 수 있습니다.

URL은 다음과 같아야 합니다.

'https://api.vercel.com/v1/edge-config/your_edge_config_id_here/items?teamId=your_team_id_here';

다음은 Vercel REST API로 Edge 설정의 항목을 가져오는 요청 예시입니다.

try {
  const readItems = await fetch(
    'https://api.vercel.com/v1/edge-config/\
        your_edge_config_id_here/items?teamId=your_team_id_here',
    {
      method: 'GET',
      headers: {
        Authorization: `Bearer ${your_vercel_api_token_here}`,
      },
    },
  );
  const result = await readItems.json();
  console.log(result);
} catch (error) {
  console.log(error);
}

이 예시에서는 Vercel REST API를 사용하여 Edge 설정의 항목을 가져옵니다.

메타데이터 읽기

Edge 설정의 메타데이터(키-값 쌍 내용은 제외)를 읽으려면 edge-config API 엔드포인트로 GET 요청을 보내면 됩니다. 아래에 설명된 대로 경로에 Edge 설정의 id를 엔드포인트에 추가하세요. Edge 설정이 팀과 연관되어 있다면, 맨 끝에 teamId 쿼리 파라미터를 추가하세요.

다음은 Vercel 팀과 연관된 Edge 설정에 대한 메타데이터를 가져오는 GET 요청 예시입니다.

try {
  const readMetadata = await fetch(
    'https://api.vercel.com/v1/edge-config/\
        your_edge_config_id_here?teamId=your_team_id_here',
    {
      method: 'GET',
      headers: {
        Authorization: `Bearer ${your_vercel_api_token_here}`,
      },
    },
  );
  const result = await readMetadata.json();
  console.log(result);
} catch (error) {
  console.log(error);
}

Edge 설정이 존재하는 경우, 응답은 Vercel REST API를 사용하여 Edge 설정을 생성할 때 받은 것과 동일한 JSON 객체가 됩니다.

{
  "createdAt": 1234567890123,
  "updatedAt": 1234567890123,
  "slug": "your_edge_config_slug_here",
  "id": "your_edge_config_id_here",
  "digest": "abc123efg456hij789",
  "sizeInBytes": 2,
  "itemCount": 0,
  "ownerId": "your_id_here"
}

이 예시를 통해, 사용자는 자신의 Edge 설정에 대한 중요한 정보를 확인할 수 있습니다.

모든 Edge 설정 목록 보기

특정 취미 계정이나 팀의 모든 Edge 설정을 edge-config API 엔드포인트로 GET 요청을 통해 나열할 수 있습니다. 예를 들어:

try {
  const listItems = await fetch(
    'https://api.vercel.com/v1/\
        edge-config?teamId=your_team_id_here',
    {
      method: 'GET',
      headers: {
        Authorization: `Bearer ${your_vercel_api_token_here}`,
      },
    },
  );
  const result = await listItems.json();
  console.log(result);
} catch (error) {
  console.log(error);
}

응답은 다음과 같아야 합니다.

[
  {
    "slug": "example_config_1",
    "itemCount": 0,
    "createdAt": 1234567890123,
    "updatedAt": 1234567890123,
    "id": "your_edge_config_id_here",
    "digest": "abc123efg456hij789",
    "sizeInBytes": 2,
    "ownerId": "your_id_here"
  },
  {
    "slug": "example_config_2",
    "itemCount": 0,
    "createdAt": 0123456789012,
    "updatedAt": 0123456789012,
    "id": "your_edge_config_id_here",
    "digest": "123efg456hij789abc",
    "sizeInBytes": 2,
    "ownerId": "your_id_here"
  }
]

이 예시를 통해 사용자는 특정 팀이나 계정에 속한 모든 Edge 설정의 목록을 확인할 수 있습니다.

Edge 설정 엔드포인트로 요청하기

프로젝트에서 연결 문자열을 환경 변수로 저장하고 SDK를 사용하여 Edge 설정 데이터를 읽는 것이 좋습니다. 그러나 Edge 설정 엔드포인트로 요청하여 Edge 설정 데이터를 읽을 수도 있습니다.

이를 위해 Edge 설정 읽기 접근 토큰을 생성하세요. 이 토큰은 Edge 설정 엔드포인트로의 요청을 인증하는 데 사용됩니다.

연결 문자열에 사용된 Edge 설정 엔드포인트는 Vercel REST API 엔드포인트와 다릅니다. 그 기본 주소는 https://edge-config.vercel.com입니다. Edge 설정 엔드포인트로 요청을 보내면 Vercel의 Edge 설정 읽기를 대안적 옵션보다 수백 밀리초 빠르게 만드는 최적화를 활용할 수 있습니다.

모든 항목 요청하기

Edge 설정의 모든 항목을 읽으려면, 아래 URL에서 적절한 Edge 설정 ID와 Edge 설정 읽기 접근 토큰을 추가하여 적절한 Edge 설정 엔드포인트로 GET 요청을 보내세요.

try {
  const readAllEdgeConfigItems = await fetch(
    'https://edge-config.vercel.com/\
        your_edge_config_id_here/\
        items?token=your_edge_config_read_access_token_here',
  );
  const result = await readAllEdgeConfigItems.json();
  console.log(result);
} catch (error) {
  console.log(error);
}

또한, 쿼리 파라미터 대신 Authorization 헤더에 Edge 설정 읽기 접근 토큰을 보낼 수도 있습니다.

try {
  const readAllWithAuth = await fetch(
    'https://edge-config.vercel.com/\
        your_edge_config_id_here/items',
    {
      method: 'GET',
      headers: {
        Authorization: `Bearer ${your_edge_config_read_access_token_here}`,
      },
    },
  );
  const result = await readAllWithAuth.json();
  console.log(result);
} catch (error) {
  console.log(error);
}

응답은 Edge 설정에 있는 모든 키-값 쌍을 담고 있는 JSON 객체가 될 것입니다. 예를 들면 다음과 같습니다.

{
  "example_key_1": "example_value_1",
  "example_key_2": "example_value_2",
  "example_key_3": "example_value_3"
}

단일 항목 요청하기

단일 항목을 요청하려면 /items 대신 /item 경로를 사용한 다음, 아래와 같이 원하는 항목의 키를 최종 경로로 추가하세요.

try {
  const readSingle = await fetch(
    'https://edge-config.vercel.com/\
        your_edge_config_id_here/item/\
        example_key_1?token=your_edge_config_read_access_token_here',
  );
  const result = await readSingle.json();
  console.log(result);
} catch (error) {
  console.log(error);
}

쿼리 파라미터 대신 Authorization 헤더에 Edge 설정 읽기 접근 토큰을 보낼 수도 있습니다.

try {
  const readSingleWithAuth = await fetch(
    'https://edge-config.vercel.com/\
        your_edge_config_id_here/item/example_key_1',
    {
      method: 'GET',
      headers: {
        Authorization: `Bearer ${your_edge_config_read_access_token_here}`,
      },
    },
  );
  const result = await readSingleWithAuth.json();
  console.log(result);
} catch (error) {
  console.log(error);
}

응답은 지정된 키에서의 원시 값이 됩니다. 예를 들어, example_key_1이 문자열 값 "example_value"를 가지고 있다면, 응답은 다음과 같을 것입니다.

"example_value"

다이제스트 요청하기

Edge 설정을 생성할 때 다이제스트라고 불리는 해시 문자열이 생성되어 붙여집니다. 이 다이제스트는 설정을 업데이트할 때마다 새로운 해시 문자열로 교체됩니다. Edge 설정이 제대로 업데이트되었는지 확인하고, 작업 중인 설정의 버전을 확인하기 위해 이 다이제스트를 확인할 수 있습니다.

Edge 설정의 다이제스트를 가져오려면 아래와 같이 edge config 엔드포인트로 GET 요청을 보내세요.

try {
  const readDigest = await fetch(
    'https://edge-config.vercel.com/\
        your_edge_config_id_here/digest?teamId=your_team_id_here&\
        token=your_edge_config_read_access_token_here',
  );
  const result = await readDigest.json();
  console.log(result);
} catch (error) {
  console.log(error);
}

요청의 Authorization 헤더에 Bearer 토큰 형식을 사용하여 Edge 설정 읽기 접근 토큰을 보낼 수도 있습니다.

try {
  const readDigestWithAuth = await fetch(
    'https://edge-config.vercel.com/\
        your_edge_config_id_here/digest?teamId=your_team_id_here',
    {
      method: 'GET',
      headers: {
        Authorization: `Bearer ${your_edge_config_read_access_token_here}`,
      },
    },
  );
  const result = await readDigestWithAuth.json();
  console.log(result);
} catch (error) {
  console.log(error);
}