앱에서 사용자 지정 엔드포인트 호출

Custom Endpoints는 Developer Console의 Unrestricted 앱만 지원합니다. Restricted 앱은 지원하지 않습니다. 엔드포인트 집합, 정의와 릴리스를 만들고 승인한 서브도메인에 배포한 뒤 앱의 인증을 연결합니다.

Developer Console 앱

1. Developer Console 앱을 생성합니다. 비밀을 서버에 보관할 수 있는 앱은 Backend service, 브라우저 클라이언트는 Client-facing application을 선택합니다.
2. 서비스 사용자로 실행하려면 Application permissions, 로그인한 사용자로 실행하려면 User permissions를 선택합니다. Client-facing application은 User permissions를 사용합니다.
3. 앱을 만든 뒤 OAuth & restrictions의 Application restrictions에서 Unrestricted로 바꿉니다. 생성 마법사에서 선택하는 항목이 아닙니다.

Unrestricted로 전환하면 기존 프로젝트 접근과 작업 제한 구성을 제거합니다. 다시 Restricted로 바꾸려면 그 구성을 다시 지정해야 합니다. 사용자 또는 서비스 사용자가 접근할 수 있는 자원을 신뢰한 앱 코드에서 사용하므로 앱 코드와 실행 주체의 권한을 함께 관리합니다.

기반 온톨로지 권한

각 엔드포인트가 실행하는 함수 또는 액션과 그 작업에 필요한 온톨로지 자원을 식별합니다. Authorization Code는 로그인한 사용자의 권한, Client Credentials는 서비스 사용자의 권한으로 접근합니다.

Unrestricted 앱에는 미리 정한 자원/작업 최대 제한 목록이 없습니다. 실제 사용자 또는 서비스 사용자에게 기반 자원 및 실행 권한을 부여하고 인증 시 요청 범위를 맞춥니다.

토큰에 요청하는 값은 작업 scope이며 자원 RID 목록이 아닙니다. 애플리케이션 제한과 grant별 조건을 따릅니다. 기반 함수/액션 권한과 엔드포인트 집합의 개발자 편집/배포 권한은 역할이 다릅니다.

서버측 호출 예제

아래 TypeScript 예는 Unrestricted Backend service와 Application permissions를 사용하는 서버측 앱입니다. 조회 전용 GET 엔드포인트가 JSON 응답을 반환한다고 가정합니다. @osdk/oauth를 의존성에 추가하고 fetch를 제공하는 서버 런타임에서 사용합니다.

환경 변수의 URL은 배포 화면에서 복사하고 client ID/secret은 해당 앱의 실제 값을 안전하게 제공합니다.

import { createConfidentialOauthClient } from "@osdk/oauth";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

const auth = createConfidentialOauthClient(
  requiredEnv("CLIENT_ID"),
  requiredEnv("CLIENT_SECRET"),
  requiredEnv("FOUNDRY_URL"),
  [],
);

export async function readCustomEndpoint(): Promise<unknown> {
  const response = await fetch(requiredEnv("CUSTOM_ENDPOINT_URL"), {
    method: "GET",
    headers: {
      Authorization: `Bearer ${await auth()}`,
      "endpoint-api-version": requiredEnv("ENDPOINT_API_VERSION"),
    },
  });
  if (!response.ok) {
    throw new Error(`Custom endpoint request failed: ${response.status}`);
  }
  return response.json();
}

FOUNDRY_URL은 https://를 포함한 인증 대상 플랫폼 URL이며 CUSTOM_ENDPOINT_URL은 사용자 지정 도메인의 실제 엔드포인트 URL입니다. ENDPOINT_API_VERSION은 배포한 릴리스입니다.

빈 scope 배열은 이 Unrestricted Client Credentials 경로에서 서비스 사용자의 전체 작업 권한을 사용합니다. 따라서 서비스 사용자 자체에 필요한 권한만 부여합니다. 이를 Authorization Code 앱에 그대로 적용하지 않습니다. client secret을 브라우저 코드나 공개 환경 변수에 넣지 않습니다.

배포 정의 확인

엔드포인트 집합의 Overview에서 배포한 엔드포인트를 inspect하면 실제 경로, 매개변수와 호출 설명을 확인할 수 있습니다.

호출 앱은 그 배포 버전의 메서드와 입력 매핑 및 응답 구조를 사용합니다. 버전 헤더를 생략하면 최신 배포로 이동하므로 다중 버전 운영과 함께 변경을 관리합니다.