TsgcHTTPRESTServer: Yeni REST Sunucu Bileşeni

TsgcHTTPServer üzerine bir REST API kurmak her zaman mümkündü, ancak birkaç şeyin her seferinde elle yazılması gerekiyordu: CORS ön kontrol yanıtı, yük dengeleyici için bir sağlık uç noktası, izleme yığını için bir metrik uç noktası ve bir müşterinin verisini diğerinden ayırmanın bir yolu. TsgcHTTPRESTServer, bunların tümünü kutudan çıktığı gibi sunan yeni bir bileşendir.

Doğrudan TsgcHTTPServer bileşeninden türer, dolayısıyla halihazırda bildiğiniz her şey geçerliliğini korur: aynı Port, aynı SSLOptions, aynı Authentication, aynı OnCommandGet olayı. TsgcHTTPServer düz bir HTTP sunucusu olarak kalır ve değişmez. Ek özellikler türetilmiş bileşende bulunur ve her biri isteğe bağlıdır.

Başlarken

Bileşen sgcHTTP_REST_Server biriminde yer alır ve SGC REST paleti sayfasında TsgcHTTPRESTServer olarak kayıtlıdır. Bir forma bırakıp Active özelliğini ayarlamanız çalışan bir HTTP sunucusu verir; ilginç kısım istek işleyicisidir.

uses
  sgcHTTP_REST_Server;

var
  oServer: TsgcHTTPRESTServer;
begin
  oServer := TsgcHTTPRESTServer.Create(nil);
  oServer.Port := 8080;
  oServer.OnCommandGet := OnServerCommandGet;
  oServer.Active := True;
end;

İşleyici standart Indy istek ve yanıt nesnelerini kullanır, dolayısıyla bir JSON yanıtı üç atamadan ibarettir:

procedure TForm1.OnServerCommandGet(AContext: TIdContext;
  ARequestInfo: TIdHTTPRequestInfo; AResponseInfo: TIdHTTPResponseInfo);
begin
  if ARequestInfo.Document = '/api/status' then
  begin
    AResponseInfo.ResponseNo := 200;
    AResponseInfo.ContentType := 'application/json';
    AResponseInfo.ContentText := '{"status":"running"}';
  end
  else
  begin
    AResponseInfo.ResponseNo := 404;
    AResponseInfo.ContentType := 'application/json';
    AResponseInfo.ContentText := '{"error":"not found"}';
  end;
end;

OnCommandGet olayı GET ve POST isteklerini alır. PUT, PATCH ve DELETE gibi fiiller, tam olarak aynı imzaya sahip olan OnCommandOther olayına gelir; bu nedenle fiillerin tamamını destekleyen bir REST kaynağı genellikle her iki olaydan da çağrılan tek bir sevk yordamı olarak yazılır.

procedure TForm1.OnServerCommandOther(AContext: TIdContext;
  ARequestInfo: TIdHTTPRequestInfo; AResponseInfo: TIdHTTPResponseInfo);
begin
  if ARequestInfo.Command = 'DELETE' then
  begin
    AResponseInfo.ResponseNo := 204;
    AResponseInfo.ContentText := '';
  end;
end;

CORS, bilinçli olarak varsayılan kapalı

API'nizi başka bir kaynaktan çağıran bir tarayıcının Access-Control-* başlıklarına ihtiyacı vardır ve gerçek isteği göndermeden önce OPTIONS ön kontrolüne bir yanıt alması gerekir. CORSOptions her ikisini de halleder.

Vurgulanmaya değer tek nokta, Enabled özelliğinin varsayılan olarak False olduğu ve gerçekten ihtiyacınız olmadıkça öyle kalması gerektiğidir. Bir yükseltmenin ardından sessizce Access-Control-Allow-Origin: * ile yanıt vermeye başlayan bir sunucu bir güvenlik gerilemesi olurdu, bu yüzden CORS kesinlikle isteğe bağlıdır.

oServer.CORSOptions.Enabled := True;
oServer.CORSOptions.AllowOrigins := 'https://app.example.com';
oServer.CORSOptions.AllowMethods := 'GET, POST, PUT, DELETE, OPTIONS';
oServer.CORSOptions.AllowHeaders := 'Content-Type, Authorization';

Bu ayarlarla ön kontrol otomatik olarak bir 204 ve üç başlıkla yanıtlanır, ayrıca her normal yanıta bu başlıklar eklenir. İşleyicinizde bir OPTIONS dalı yazmanız gerekmez.

API kimlik doğrulamalı olduğunda * yerine açık bir kaynak belirtmeyi tercih edin. Joker karakterli bir kaynak ile kimlik bilgilerinin birlikte kullanımı tarayıcılar tarafından zaten reddedilir ve gerçekten hizmet verdiğiniz kaynakları listelemek daha güvenli bir varsayılandır.

Yazmadan sağlık ve metrikler

ServerStats özelliğine bir TsgcHTTPServerStats bileşeni bağlayın; sunucu iki operasyonel uç noktayı yanıtlayabilir hale gelir. Her ikisi de siz tek tek etkinleştirene kadar devre dışıdır.

oStats := TsgcHTTPServerStats.Create(nil);
oStats.Endpoints.Health.Enabled := True;
oStats.Endpoints.Metrics.Enabled := True;
oServer.ServerStats := oStats;

/health bir yük dengeleyici yoklaması için uygun küçük bir JSON belgesiyle yanıt verir:

{"status":"ok","uptime":3600,"connections":12,"requests":48120,
 "responses":{"1xx":0,"2xx":47800,"3xx":10,"4xx":300,"5xx":10},
 "latency":{"min":0,"avg":4,"max":180}}

/metrics Prometheus metin sunum biçiminde yanıt verir, böylece arada hiçbir adaptör olmadan toplanabilir:

# HELP sgc_server_requests_total Total requests served
# TYPE sgc_server_requests_total counter
sgc_server_requests_total 48120
# HELP sgc_server_request_duration_ms_avg Average request duration
# TYPE sgc_server_request_duration_ms_avg gauge
sgc_server_request_duration_ms_avg 4

/metrics ve /health kendi rotalarınızla çakışıyorsa her iki yol da yapılandırılabilir:

oStats.Endpoints.Metrics.Path := '/internal/metrics';
oStats.Endpoints.Health.Path := '/internal/health';

Bu uç noktalar kimlik doğrulama kapısından sonra sunulur, dolayısıyla sunucunun halihazırda uyguladığı kimlik doğrulamayı devralırlar. Sunucunun kendisi herkese açık olmadıkça hiçbir zaman herkese açık değildirler. Bunu her iki yönde de bilmekte fayda var: bu, onları varsayılan olarak özel tutar ve sunucu kimlik bilgisi gerektirdiğinde bir izleme toplayıcısının da kimlik bilgilerine ihtiyaç duyacağı anlamına gelir.

API ile birlikte statik içerik sunmak

DocumentRoot özelliği TsgcHTTPServer bileşeninden devralınır ve çalışmaya devam eder, böylece tek bir sunucu küçük bir ön yüzü ve onun konuştuğu API'yi birlikte barındırabilir. İşleyicinizin yanıtlamadığı her şey belge köküne düşer.

oServer.DocumentRoot := 'C:\www\app';
oServer.HTTPCompression.Enabled := True;
oServer.HTTPCompression.MinSize := 1024;

TLS

Temel sunucuya göre hiçbir şey değişmez. SSL özelliğini ayarlayın ve SSLOptions özelliğini her zamanki gibi doldurun:

oServer.SSL := True;
oServer.SSLOptions.Port := 443;
oServer.Port := 443;

Sırada ne var

Bileşen ayrıca tek bir sunucuyu çok müşterili bir sunucuya dönüştüren bir Tenancy özelliği ve salt okunur bir Tenant özelliği yayımlar; ayrıca Authentication seçenekleri bir kullanıcı deposu bileşenini kabul eder, böylece kimlik bilgilerini bir TStringList içinde tutmak zorunda kalmazsınız. Bunlar ikinci makalede ele alınıyor, üçüncüsü ise rotaların, doğrulamanın ve belgelerin tamamı tek bir dosyadan gelsin diye tüm bunların önüne bir OpenAPI sözleşmesinin nasıl konulacağını gösteriyor.

TsgcHTTPRESTServer şu anda kullanılabilir durumda. En son derlemeyi sgcWebSockets indirme sayfasından indirin.