외부 서비스에 대한 API 사양 정의

학습 목표

이 유닛을 완료하면 다음을 수행할 수 있습니다.

API 사양의 목적을 설명할 수 있습니다.
지원되는 외부 서비스 스키마 정의의 요소를 설명할 수 있습니다.
API 사양 실패를 야기할 수 있는 세 가지 문제를 설명할 수 있습니다.

스키마 정의가 필요한 이유는?

지난 유닛에서는 API 사양이란 API가 수행할 수 있는 작업을 정의하는 설명 스키마를 포함하는 파일이라는 것을 배웠습니다. 외부 서비스 등록을 위한 API 사양을 만들 일이 없다고 하더라도 그 목적과 사용 방법을 알아두는 것이 좋습니다.

REST 기반 은행 API가 있다고 상상해 보세요. 은행의 REST 기반 API 구조를 설명할 수 있도록 공통적이고 표준화된 형식이 필요합니다. API 사양을 입력합니다. Salesforce는 설명 형식에 일반적으로 채택되는 OpenAPI 사양을 사용합니다.

API 사양에는 호출 또는 요청에 포함할 수 있는 조직에서 외부 웹 서비스에 대한 입출력 유형을 설명하는 스키마 정의가 포함되어 있습니다. 예를 들어 호출에는 숫자 입력으로 ID 또는 텍스트 출력으로 name이 포함될 수 있습니다.

API 사양에는 액세스할 수 있는 REST 기반 API 웹 서비스에 대한 엔드포인트 정보 및 인증 매개 변수도 포함되어 있습니다. (엔드포인트는 외부 서비스가 상호 작용하는 웹 서비스 리소스를 노출한다는 것을 기억하세요.) 예를 들어 가상 은행 웹 서비스의 이 API 사양에는 은행 계좌를 추가 및 삭제하는 방법이 포함되어 있습니다. https://th-external-services.herokuapp.com/accounts/schema

실제 애플리케이션에서는 보안 모범 사례에 따라 은행 API에 액세스하기 전에 인증 단계를 포함합니다.

가상 은행의 API 사양은 사람이 읽을 수 있는 구조화된 데이터이니 한번 살펴보겠습니다.

다음은 스키마의 기본 계정 작업입니다.

경로 작업: /accounts/{accountName}	설명
GET	계정 검색
POST	계정 추가
PUT	계정 업데이트
DELETE	계정 삭제

다음은 GET 메서드에 대한 정보가 포함된 API 사양 스키마의 일부 코드 조각입니다. 모를 경우 GET 메서드는 단순히 웹 서비스에서 리소스 정보를 검색합니다. 이 특정 GET 메서드는 {accountName}이(가) 지정된 계정이면 /accounts/{accountName}의 경우 리소스 경로를 사용하여 계정에 대한 정보를 검색("가져오기")합니다. “parameters" 아래를 보면 "name":"accountName"을 볼 수 있습니다. 이 매개 변수는 지정한 계정 이름과 일치해야 하며 필수 ("required":true)입니다. 또한 문자열 형식을 취해야 합니다.

"paths": {
	"/accounts/{accountName}": 
	{ "get": 
		{ "operationId": "getAccount", 
		"summary": "Retrieves an account", 
		"description": "Retrieves the account with specific name",
		"consumes": ["text/plain"], 
		"produces": ["application/json"], 
		"parameters": [{ 
		"name": "accountName", 
		"in": "path", 
		"required": true, 
		"type": "string", 
		"description": "Name of the account" }], 
		"responses": { 
			"200": { 
				"description": "The response when system finds an account with given name", 
				"schema": { 
				"$ref": "#/definitions/accountDetails" } }, "400": 
				{ "description": "Error response if the account name parameter is less than minimum characters",
			"schema": 
			{ "$ref": "#/definitions/errorModel" } }, 
			"404": { 
			"description": "Error response if the account is not supported by service or account is not found",
			"schema": { "
			$ref": "#/definitions/errorModel" 
			}

이는 훨씬 더 큰 스키마 정의의 일부일 뿐입니다. 그러나 외부 서비스에서 사용하도록 설계되었지만 사람이 읽을 수도 있습니다. 또한 외부 서비스가 작업을 처리할 수 있도록 논리적인 방식으로 형식이 지정되어 Flow Builder 또는 Einstein Bots와 같은 도구에서 호출 가능한 작업으로 처리할 수 있습니다.

다음 단계에서는 API 사양을 선언적으로 등록하는 방법을 살펴보겠습니다. 하지만 먼저 지원되는 유효한 스키마 정의(API 사양 문서에 포함된 개별 API 기능에 대한 자세한 설명)를 구성하는 요소에 대해 다뤄보겠습니다.

지원되는 유효한 스키마는 무엇인가요?

이제 API 사양이 무엇인지 알아봤습니다. 그러나 지원되는 유효한 스키마란 무엇을 의미하나요?

OpenAPI 사양에서 정의하는 스키마 유효성 검사 요구 사항과 특정 외부 서비스 스키마 요구 사항도 있습니다. 외부 서비스는 이러한 요구 사항이 모두 충족될 때 스키마를 적절하게 지원하고 웹 서비스를 호출할 수 있습니다.

스키마 검증에 대한 입문서

스키마는 사람이 읽을 수 있지만 기계도 읽을 수 있어야 합니다. 외부 서비스에서 쉽게 사용할 수 있도록 논리적 구조를 따라야 합니다. 잘못 구조화된 스키마는 외부 웹 서비스가 통신할 수 없고(오류 및 예외 메시지 반환) 궁극적으로 외부 서비스가 이를 수집할 수 없음을 의미합니다. 구조적, 논리적 및 구문 제한을 충족하는 것은 스키마 유효성 검사의 필수 첫 번째 단계입니다. OpenAPI 사양은 이러한 일반 규칙을 정의하고 외부 웹 서비스를 호출할 경우 추측을 배제합니다.

지원되는 외부 서비스 스키마

스키마 유효성 검사에 대한 일반 OpenAPI 지침 외에도 외부 서비스별 스키마 제한 사항도 있습니다. 외부 서비스에 API 사양을 등록하기 전에 이러한 요구 사항을 검토해야 합니다. 외부 서비스에서 지원되는 스키마는 두 스키마가 모두 OpenAPI 사양에 따라 유효하다는 것을 뜻합니다. 이는 또한 특정 외부 서비스 요구 사항도 준수함을 의미합니다. 예를 들어, API 사양이 파일 크기 제한을 초과하거나 총 개체 또는 작업 수에 대한 제한을 초과하면 API 사양이 등록 프로세스에 실패할 수 있습니다.

외부 서비스 지원 스키마를 만들기 위한 주요 요구 사항 목록은 Salesforce 도움말: 외부 서비스 고려 사항을 참조하세요.