TsgcOpenAPI_Client 는 OpenAPI 사양에서 HTTP 요청을 수행하는 주요 메서드와 속성을 캡슐화하는 비시각적 구성 요소입니다.
sgcOpenAPI Parser로 생성된 모든 OpenAPI 인터페이스에는 2개의 메서드가 있습니다.
예제
Abstractapi를 사용하여 IP 주소의 위치 정보를 검색합니다.
GetOpenAPIClient.Retrieve_the_location_of_an_IP_address('your api', '80.258.15.2');
auth2Code: 단일 페이지 애플리케이션, 웹 애플리케이션, 네이티브 설치 애플리케이션을 포함한 대부분의 애플리케이션 유형에서 인증 및 권한 부여를 수행하는 데 사용됩니다. 이 흐름을 통해 앱은 보안 리소스에 액세스하는 데 사용할 수 있는 access_token, 추가 access_token을 얻기 위한 갱신 토큰, 그리고 로그인한 사용자의 ID 토큰을 안전하게 획득할 수 있습니다.
auth2ClientCredentials: 이 유형의 부여는 일반적으로 사용자와의 즉각적인 상호 작용 없이 백그라운드에서 실행되어야 하는 서버 간 상호 작용에 사용됩니다. 이러한 유형의 애플리케이션은 종종 데몬 또는 서비스 계정이라고 합니다.
자세한 내용은 OAuth2를 참조하십시오.
HTTP/1 프로토콜을 사용하여 보안 SSL/TLS 서버에 연결하는 방법을 구성할 수 있습니다
생성된 클라이언트는 기본적으로 서버의 인증서를 검증합니다. 이전 버전에서는 검증하지 않았습니다. 신뢰는 OpenSSL 기본 검증 경로에서 얻으므로, CA 스토어가 구성되지 않은 컴퓨터에서는 TLSOptions.RootCertFile에 신뢰할 수 있는 루트 인증서가 들어 있는 파일을 설정하십시오. 자체 서명된 엔드포인트나 테스트 엔드포인트에 연결하려면 TLSOptions.VerifyCertificate := False로 설정하십시오.
ALPNProtocols: 서버로 전송될 ALPN 프로토콜 목록입니다.
RootCertFile: 루트 인증서 파일의 경로입니다.
CertFile: 인증서 파일 경로입니다.
KeyFile: 인증서 키 파일의 경로입니다.
Password: 인증서가 비밀번호로 보호된 경우 여기에 설정하십시오.
VerifyCertificate: 인증서를 검증해야 하는 경우 이 속성을 활성화하십시오. OpenAPI 클라이언트는 기본적으로 이 속성을 활성화하며, 자체 서명된 인증서를 허용하려면 False로 설정하십시오.
VerifyDepth: X.509 인증서에 대해 검증이 수행될 때 허용되는 최대 링크 수를 나타내는 Integer 속성입니다.
Version: 기본적으로 TLS 1.0을 사용하며, 서버가 더 높은 TLS 버전을 요구하는 경우 여기에서 선택할 수 있습니다.
IOHandler: TLS를 사용하여 연결하는 데 사용할 라이브러리를 선택하십시오.
iohOpenSSL: OpenSSL 라이브러리를 사용하며 Indy 구성 요소의 기본값입니다. win32/win64용 openssl 라이브러리를 배포해야 합니다.
iohSChannel: Microsoft가 Windows용으로 구현한 보안 프로토콜인 Secure Channel을 사용하며, openssl 라이브러리를 배포할 필요가 없습니다. Windows 32/64비트에서만 작동합니다.
OpenSSL_Options: openSSL 라이브러리의 구성입니다.
APIVersion: 어떤 OpenSSL API를 사용할지 정의할 수 있게 합니다.
oslAPI_1_0: API 1.0 OpenSSL을 사용하며, Indy가 지원하는 최신 버전입니다
oslAPI_1_1: API 1.1 OpenSSL을 사용하며, 당사의 사용자 정의 Indy 라이브러리가 필요하고 OpenSSL 1.1.1 라이브러리(TLS 1.3 지원 포함)를 사용할 수 있게 합니다.
oslAPI_3_0: API 3.0 OpenSSL을 사용하며, 사용자 지정 Indy 라이브러리가 필요하고 OpenSSL 3.0.0 라이브러리(TLS 1.3 지원 포함)를 사용할 수 있습니다.
LibPath: 여기에서 openSSL 라이브러리가 위치한 곳을 구성할 수 있습니다.
oslpNone: 이것이 기본값이며, openSSL 라이브러리는 바이너리가 있는 동일한 폴더 또는 알려진 경로에 있어야 합니다.
oslpDefaultFolder: 모든 IDE 퍼스낼리티에 대해 라이브러리가 위치해야 하는 openSSL 경로를 자동으로 설정합니다.
oslpCustomFolder: 이 옵션이 선택된 경우, LibPathCustom 속성에 전체 경로를 정의하십시오.
LibPathCustom: LibPath = oslpCustomFolder일 때 openSSL 라이브러리가 있는 전체 경로를 여기에 정의하십시오.
UnixSymLinks: Unix 시스템에서 SymLinks 로딩을 활성화하거나 비활성화합니다(기본적으로 활성화되어 있으며, OSX64에서는 예외):
oslsSymLinksDefault: 기본적으로 활성화되지만 OSX64에서는 예외입니다(MacOS Monterey 이후 버전 없이 라이브러리를 로드하려고 하면 실패함).
oslsSymLinksLoadFirst: 버전 라이브러리를 로드하기 전에 SymLink를 로드하고 먼저 시도합니다.
oslsSymLinksLoad: 버전 라이브러리를 로드하려고 시도한 후 SymLinks를 로드합니다.
oslsSymLinksDontLoad: SymLinks를 로드하지 않습니다.
SChannel_Options: Windows Certificate Store의 인증서를 사용할 수 있게 합니다.
CertHash: 는 인증서 Hash입니다. powershell에서 dir 명령을 실행하여 인증서 Hash를 찾을 수 있습니다.
CipherList: 여기에서 어떤 Cipher가 사용될지 설정할 수 있습니다(":"로 구분). 예: CALG_AES_256:CALG_AES_128
CertStoreName: 인증서가 저장된 스토어 이름. 아래 중 하나를 선택하십시오:
scsnMY(기본값)
scsnCA
scsnRoot
scsnTrust
CertStorePath: 인증서가 저장된 저장소 경로입니다. 아래에서 하나를 선택하십시오:
scspStoreCurrentUser (기본값)
scspStoreLocalMachine
프록시를 통한 연결을 구성하려면 이 속성을 사용하십시오.
Enabled: 프록시 연결을 활성화하려면 true로 설정하십시오.
Host: 프록시 서버 주소
Port: 프록시 서버 포트
UserName/Password: 프록시에 연결하기 위한 인증입니다. 필요한 경우에만 사용합니다.
ProxyType: 다음 프록시가 지원됩니다:
Log 속성이 활성화되면 소켓 메시지를 지정된 로그 파일에 저장하며, 디버깅에 유용합니다.
Log: HTTP 요청을 텍스트 파일에 저장하려면 활성화하십시오.
LogFileName: 파일 이름의 전체 경로입니다.
OpenAPI 클라이언트를 사용자 정의하는 데 사용할 수 있는 기타 속성:
EncodeBodyAsUTF8: 활성화하면 요청 본문이 UTF-8로 인코딩됩니다(기본값 true). JSON 문서는 RFC 8259에 따라 UTF-8이며, ANSI로 인코딩된 본문은 ASCII 범위를 벗어난 모든 문자를 깨뜨립니다.
사양에서 생성된 클래스(DTO)는 JSON으로 기록되는 방식을 사용자 지정할 수 있도록 다음 속성을 제공합니다:
JSONIgnoreEmptyStrings: 기본값은 False이므로 빈 문자열을 담고 있는 필드는 "field": ""로 기록됩니다. 빈 문자열도 하나의 값이므로 서버는 이를 한 번도 설정되지 않은 필드와 구분할 수 없습니다. 빈 문자열을 JSON에서 제외하려면 True로 설정하십시오. 이전 버전의 동작이 그러했습니다.
JSONIgnoreNullValues: 기본값은 True이므로 null은 JSON에 기록되지 않습니다. null은 이 속성만으로 제어되며 JSONIgnoreEmptyStrings와는 무관합니다. 명시적인 null을 기록하려면 False로 설정하십시오. JSON Merge Patch(RFC 7386)에서 멤버를 삭제할 때 필요합니다.
요청의 결과는 TsgcOpenAPIResponse 객체로 반환됩니다.
ResponseStream: 응답 본문이 기록되는 스트림입니다. 다운로드를 직접 저장하려면 사용자 스트림을 할당하십시오.
OwnsResponseStream: 호출자가 할당한 스트림은 더 이상 응답과 함께 해제되지 않으며, 소유권은 호출자가 유지합니다. 이전 동작으로 되돌려 응답이 스트림을 해제하도록 하려면 True로 설정하십시오.
사양에서 in: cookie로 선언된 매개변수가 지원됩니다. 한 요청의 모든 쿠키 매개변수는 RFC 6265가 요구하는 대로 하나의 Cookie 헤더에 함께 전송됩니다.
기본적으로 OpenAPI 클라이언트는 요청을 동기적으로 실행합니다. 비동기 API를 사용하면 백그라운드 스레드에서 요청을 실행하고 이벤트를 통해 알림을 받을 수 있으며, 이를 통해 사용자 인터페이스의 응답성을 유지하고 요청을 취소할 수 있습니다.
HTTP_REQUEST_Async: 워커 스레드에서 요청을 실행합니다. 클라이언트가 요청 객체의 소유권을 가집니다.
CancelAsync: 진행 중인 요청을 취소합니다.
SynchronizeEvents: True이면 이벤트가 메인 스레드로 마샬링됩니다. 기본값은 False이며 이벤트는 워커 스레드에서 발생합니다.
결과는 다음 이벤트를 통해 전달됩니다:
OnResponse: 요청이 완료되었으며, 응답이 매개변수로 전달됩니다.
OnError: 요청이 실패했으며, 예외가 매개변수로 전달됩니다.
OnCancel: 요청이 CancelAsync에 의해 취소되었습니다.
클라이언트는 자신의 OnResponse, OnError, OnCancel 이벤트 핸들러 내부에서 해제할 수 없습니다. 클라이언트를 소멸시키면 워커 스레드를 기다리는데, 그 스레드가 바로 핸들러를 실행 중인 스레드이므로 애플리케이션이 멈추게 됩니다. 대신 명확한 오류가 발생하므로, 이벤트 핸들러가 반환된 후에 클라이언트를 해제하십시오.
OpenAPI Client를 사용할 때 처리할 수 있는 이벤트 목록은 아래를 참조하십시오.
OnBeforeRequest
이 이벤트는 HTTP 요청이 호출되기 전에 호출됩니다. 매개변수 이름, 헤더, 보안 등을 사용자 지정할 수 있습니다. 아래에서 일부 매개변수의 이름을 교체하는 방법의 예제를 확인하십시오.
procedure OnBeforeRequestEvent(Sender: TObject; const aRequest: TsgcOpenAPIRequest);
var
i: Integer;
oParameter: TsgcOpenAPIParameter;
begin
for i := 0 to aRequest.Parameters.Count - 1 do
begin
oParameter := aRequest.Parameters[i];
if oParameter._Name = 'meta-modified-from' then
oParameter._name := 'eventDateTime-from';
if oParameter._Name = 'meta-modified-to' then
oParameter._name := 'eventDateTime-to';
end;
end;
OnUpload
이 이벤트는 파일이 업로드될 때 호출됩니다. 이 이벤트를 사용하여 업로드 진행 상황을 알 수 있습니다.
OnDownload
이 이벤트는 파일이 다운로드될 때 호출되며, 이 이벤트를 사용하여 다운로드의 진행 상황을 알 수 있습니다.
OnSSLVerifyPeer
verify certificate가 활성화된 경우, 이 이벤트에서 서버 인증서를 확인하고 수락할지 여부를 결정할 수 있습니다.
OnSSLGetHandler
이 이벤트는 SSL 핸들러가 생성되기 전에 발생합니다. 여기에서 자체 SSL 핸들러(TIdServerIOHandlerSSLBase 또는 TIdIOHandlerSSLBase에서 상속되어야 함)를 생성하고 필요한 속성을 설정할 수 있습니다
OnSSLAfterCreateHandler
사용자 정의 SSL 객체가 생성되지 않은 경우, OpenSSL 핸들러를 사용하여 기본적으로 생성합니다. SSL Handler 속성에 액세스하여 필요한 경우 수정할 수 있습니다