sgcOpenAPI Hızlı Başlangıç

Bir bakışta

Bırakılacak bir bileşen yok

Başlamadan önce anlamanız gereken tek şey budur. sgcOpenAPI IDE paletine hiçbir şey kaydetmez ve tasarım zamanı paketi içermez. İş akışı önce üretmek, sonra kullanmaktır.

Araç

Hem bir GUI sihirbazı hem de bir komut satırı olan sgcOpenAPI.exe. Bir belirtimi okur ve tek bir .pas dosyası yazar.

Ne yazar

TsgcOpenAPI_Client sınıfından türeyen bir istemci sınıfı, işlem başına bir metot, istek ve yanıt sınıfları ve hazır bir tekil nesne döndüren GetOpenAPIClient işlevi içeren bir unit.

Nasıl çağırırsınız

Üretilen unit'i projenize ekleyin, uses yan tümcesine koyun ve GetOpenAPIClient.YourOperation(...) çağırın. Sonuç, işiniz bittiğinde serbest bıraktığınız bir yanıt nesnesidir.

Paketler

AWS, Azure, Google ve Microsoft için önceden derlenmiş SDK'ları içeren beş çalışma zamanı paketi gelir. Bunlar kurmak için değil derlemek içindir, çünkü eklenecek bir palet sayfası yoktur.

Başlamadan önce

Gereksinimler ve sürümler

Sürüm sütunu, kodu kısıtlayan tanımdır; yanında ürünün kendi Source/sgcVer.inc dosyasında bulunduğu satır yer alır.

Konu	Değer
IDE	Üretilen kod için Delphi 7'den RAD Studio 13'e kadar. Türlü yanıt nesneleri XE7 veya üzerini gerektirir ve pakette gelen demo bunları `{$IF CompilerVersion >= 28.0}` ile korur. Bunun altında üretilen metot düz bir dize döndürür.
C++Builder	Üretilen istemci için desteklenmez. `sgcHTTP_OpenAPI_Client.pas` dosyasının tamamını kısıtlayan `SGC_HTTP_OPENAPI`, ürünün `sgcVer.inc` dosyasının 702. satırında bir `{$IFNDEF BCB}` içinde tanımlanır; bu nedenle bir C++Builder derlemesi o unit'i hiçbir şeye derler.
Sürüm	sgcOpenAPI derlemeleri en düşük iki kademeye sabitlenmiştir. `sgcVer.inc` dosyasının 7 ile 10. satırları `{$IFDEF SGC_OPENAPI}` ve ardından `{$UNDEF SGC_EDT_PRO}`, `{$UNDEF SGC_EDT_ENT}` ile `{$UNDEF SGC_EDT_ALL}` ifadelerini içerir; Core ve Standard tanımlı kalır. Ticari kademeler özelliğe göre değil, kullanıcı sayısına göredir.
Sunucu üretimi	Aynı derleme 11. satırda `SGC_HTTP_OPENAPI_SERVER` tanımlar; böylece üretici bir istemcinin yanı sıra bir sunucu iskeleti de üretebilir. Komut satırında `-s` verin.
Platformlar	Unit kapsamında işletim sistemi koruması yoktur. Üretilen istemci temel unit'indeki tek koşullar olağan `{$IFDEF MSWINDOWS}` içe aktarması ve iş parçacığı kimliği türü değişimleridir; dolayısıyla Windows, macOS, Linux, Android ve iOS'un hepsi derlenir.
Lisans etkinleştirme	Makine etkinleştirilmemişse komut satırına `-user` ve `-password` verin, aksi hâlde çalıştırma 2 koduyla çıkar.

Üretici JSON ve YAML kabul eder ve ikisini de yerel olarak okur. Swagger 2.0 belgesi de yerel olarak OpenAPI 3'e dönüştürülür. Uzak dönüştürücü -r ile isteğe bağlıdır ve belirtiminizi üçüncü taraf bir sunucuya yükler; bu nedenle siz istemedikçe kapalı kalır.

1. Adım

Kurun ve üretin

Kurulacak bir tasarım zamanı paketi olmadığından kurulum diğer ürünlere göre daha kısadır.

1. Zip dosyasını açın

İndirdiğiniz dosyayı aşağıda {$DIR} olarak adlandırılan bir klasöre açın. Demos\, Bin\ ve Source\ klasörlerini alırsınız.

2. Kitaplık yolu

Tools, Options, Library. Üretilen unit'lerin ve istemci temel sınıfının çözülmesi için {$DIR}\Source yolunu ekleyin. IDE'ye kurulacak bir şey yoktur.

3. İsteğe bağlı, önceden derlenmiş bir SDK derleyin

Birlikte gelen SDK'lardan birini istiyorsanız, {$DIR}\Packages\ altında eşleşen çalışma zamanı paketini açın ve derleyin. Bunlar çalışma zamanı paketleridir; kurmayın, derleyin.

4. Bir istemci üretin

Sihirbaz için Bin\sgcOpenAPI.exe dosyasını çalıştırın veya komut satırını kullanın. Bir girdi, bir çıktı ve elinizde bir unit olur.

5. Unit'i projenize ekleyin

Üretilen .pas dosyasını diğer unit'lerinizin yanına koyun, projeye ekleyin ve uses yan tümcenize yazın. Tüm entegrasyon budur.

QuickStart

Belirtim girer, çalışan istemci çıkar

Bir komut satırı unit'i üretir. Bir çağrı onu kullanır. Üçüncü sekme ilk gün bilmeye değer anahtarları gösterir.

komut satırı

> sgcOpenAPI.exe -i "geolocation.json" -o "geolocation.pas"

File successfully created geolocation.pas

İki anahtar da zorunludur. -i yerel bir dosya veya URL alır ve JSON ile YAML kabul eder; -o ise yazılacak Pascal unit'idir. Tıklamayı tercih ederseniz aynı çalıştırılabilir dosyada bir GUI sihirbazı vardır. Üretilen .pas dosyasını projenize ekleyin, kullanıma hazırdır.

fGeolocation.pas

uses
  geolocation;   // the unit you just generated

procedure TfrmGeolocation.btnGeolocationClick(Sender: TObject);
var
  oResponse: TsgcOpenAPI_Retrieve_the_location_of_an_IP_address_Response;
begin
  oResponse := GetOpenAPIClient.Retrieve_the_location_of_an_IP_address(
    txtAPIKey.Text, txtIPAddress.Text);
  try
    if oResponse.IsSuccessful then
      memoResponse.Lines.Text :=
        'country: ' + oResponse.Successful.Country + #13#10 +
        'city: ' + oResponse.Successful.City
    else
      memoResponse.Lines.Text := oResponse.ResponseError;
  finally
    oResponse.Free;
  end;
end;

GetOpenAPIClient unit'in içine üretilir ve parametre almaz. İşlem başına bir metot vardır ve adı işlem kimliğinden verilir. Yanıt nesnesini serbest bırakmak size aittir; demonun bir try finally kullanmasının nedeni budur. XE7 öncesi Delphi sürümlerinde üretilen metot bunun yerine düz bir dize döndürür ve pakette gelen demo türlü yolu {$IF CompilerVersion >= 28.0} ile korur.

komut satırı

-s              generate a server stub instead of a client
-a 3            add an OAuth2 flow to the generated client
                (0 none, 1 basic, 2 token, 3 oauth2, 4 jwt)
-u <url>        set the base url the generated client uses
-m 1            name methods from summary rather than operationid
                (0 operationid, 1 summary, 2 endpoint)
-x <list|file>  exclude operations, as "VERB endpoint"
-p              generate only the classes the kept operations use
-nc             do not create pascal classes
-l              show progress messages (errors are always shown)
-user -password activate the licence on this machine

Büyük bir belirtimde -x ve -p birlikte, IDE'de açabileceğiniz bir unit ile açamayacağınız bir unit arasındaki farktır. -r de vardır ve belirtimin tamamını üçüncü taraf bir dönüştürücüye yüklediği için bilerek varsayılan olarak kapalıdır.

Üretme komutu, aracın kendi yardımının yazdırdığı kullanım satırıdır. Çağrı, form denetimleri sabit değerlerle değiştirilmiş olarak paketle gelen Demos\20.Client\abstractapi.com\geolocation\fGeolocation.pas demosudur. Bu demo belirtimi getirir ve unit'i sizin üretmenizi bekler; hızlı başlangıcın üreticiyle başlamasının nedeni budur.

2. Adım

Üreticinin başarılı olduğunu kontrol edin

Bakılacak iki şey var ve biri betiklenebilir.

İleti

Araç, çıktı yolunun ardından File successfully created yazdırır. Hatalar her zaman standart hataya gider; bu nedenle hiçbir şey yazmayan sessiz bir çalıştırma sessiz değildir.

Çıkış kodu

0 başarı, 1 hata, 2 geçersiz lisans, 3 geçersiz anahtar, 4 geçersiz yapılandırma dosyası, 5 geçersiz girdi dosyası, 6 geçersiz çıktı dosyası, 7 belirtim geçerli bir OpenAPI 3 belgesine dönüştürülemedi. Bunu derleme betiğinizde sınayın.

Unit derleniyor

Üretilen .pas dosyasını projeye ekleyin ve derleyin. Kitaplık yolunda {$DIR}\Source dışında hiçbir şeye ihtiyaç duymadan derlenmelidir.

`IsSuccessful`

Çalışma zamanında yanıt nesnesi size söyler. False olduğunda ResponseError iletiyi, ResponseCode ise HTTP durumunu taşır.

Sık karşılaşılan sorunlar

İlk seferde genellikle ne ters gider

İlk çalıştırmaların neredeyse tamamı altı sorundan kaynaklanır.

Paletteki bir bileşeni arıyorsunuz

Yok. sgcOpenAPI hiçbir bileşen kaydetmez ve tasarım zamanı paketi içermez. Üretilen unit entegrasyon noktasıdır ve istemciye GetOpenAPIClient ile ulaşırsınız.

Demoda adı geçen unit mevcut değil

Bu beklenen bir durumdur. Demolar belirtimi getirir, üretilen unit'i getirmez; bu nedenle önce üreticiyi çalıştırırsınız. Geolocation demosu geolocation adlı bir unit gerektirir ve bu unit geolocation.json dosyasından çıkar.

Çıkış kodu 2

Lisans bu makinede etkinleştirilmemiş. Komut satırında -user ve -password verin.

Türlü yanıt nesnesi derlenmiyor

Türlü yanıtlar XE7 veya üzerini gerektirir. Pakette gelen demo bunları {$IF CompilerVersion >= 28.0} ile korur ve eski derleyicilerde düz bir dize döndüren bir metoda geri döner. Delphi 7'yi destekliyorsanız bu korumayı tutun.

C++Builder altında hiçbir şey derlenmiyor

SGC_HTTP_OPENAPI, ürünün sgcVer.inc dosyasının 702. satırında bir {$IFNDEF BCB} içinde tanımlanır; bu nedenle üretilen istemci temel sınıfı C++Builder için hiç derlenmez.

Belirtim dönüştürülmüyor

Çıkış kodu 7, belgenin geçerli bir OpenAPI 3 belgesine dönüştürülemediği anlamına gelir. YAML ve Swagger 2.0 yerel olarak işlenir; -r arkasındaki uzak dönüştürücü kaçış yoludur ve dosyanın tamamını eSeGeCe'nin denetlemediği bir sunucuya yükler.

Daha derine inin

İlk istemcinin ötesinde

Dört yön, hepsi aynı üreticiden.

İstemci değil, sunucu üretin

-s verin; üretici bunun yerine bir sunucu iskeleti üretir. Sunucu demoları, üretilen işlemlerin belirtime göre nasıl dağıtıldığını ve doğrulandığını gösterir.

sgcOpenAPI Sunucu

Önceden derlenmiş SDK'ları kullanın

AWS, Azure, Google ve Microsoft dahil binden fazla belirtim zaten üretilmiş ve pakete eklenmiştir. İstediğiniz paketi derleyin ve üretme adımını tamamen atlayın.

Birlikte gelen API'ler

Ürettiğinizi kırpın

-x işlemleri fiil ve uç noktaya göre dışlar, -p ise kalan hiçbir işlemin kullanmadığı sınıfları budar. Büyük bir belirtimde bu, açabileceğiniz bir unit ile açamayacağınız bir unit arasındaki farktır.

Ayrıştırıcı

Kimlik doğrulamayı bağlayın

Üretilen istemci bir Authentication özelliği taşır ve -a üretim sırasında şemayı seçer: yok, basic, belirteç, OAuth2 veya JWT.

sgcOpenAPI özellikleri

Kaynaklar

Başvuru, demolar ve belgeler

Demo projeleri indirmenin içinde, Demos\ altında gelir: önceden derlenmiş SDK'lar, üretilmiş bir istemci ve iki sunucu örneği.

	sgcOpenAPI ne yapar Ayrıştırıcı, üretici ve sunucu bileşeni tek bir sayfada.	Aç
	Ayrıştırıcı Bir belirtimin nasıl okunduğu, doğrulandığı ve Pascal türlerine dönüştürüldüğü.	Aç
	Sunucu bileşeni Bir API'yi tüketmek yerine bir belirtimden sunmak.	Aç
	Birlikte gelen API'ler Derlemeye hazır gelen önceden derlenmiş SDK'lar.	Aç
	Denemeyi indirin Üretici ve kaynak, süre sınırlı.	Aç
	OpenAPI nedir Belirtim biçiminin kendisi sizin için yeniyse arka plan bilgisi.	Aç

İlgili okumalar: OpenAPI'den Delphi istemcisi üretme, şemaları paketleme, sgcOpenAPI ile swagger-codegen karşılaştırması ve OpenAPI sunucusu. Her ürünün kendi hızlı başlangıcı vardır ve başlarken sayfasında listelenir.

SSS

sgcOpenAPI hızlı başlangıç soruları

Hiçbirini. sgcOpenAPI bir kod üreticisi ve bir çalışma zamanı kitaplığıdır ve IDE paletine hiçbir şey kaydetmez. Üründe hiç tasarım zamanı paketi yoktur. sgcOpenAPI.exe dosyasını bir belirtime karşı çalıştırırsınız, tek bir Pascal unit'i yazar ve o unit'i projenize eklersiniz. Onun içinde GetOpenAPIClient, işlem başına bir metodu olan hazır bir istemci nesnesi döndürür.

Araç bunu kendi yardımında yazdırır: sgcOpenAPI.exe -i "c:\openapi.json" -o "c:\openapi.pas". İki anahtar da zorunludur. -i yerel bir dosya veya URL alır ve hem JSON hem de YAML kabul edilir. -o yazılacak Pascal unit'idir. Bir değer, -i:"c:\openapi.json" örneğindeki gibi iki nokta üst üste sonrasına da eklenebilir.

İki yolla. Araç, çıktı yolunun ardından File successfully created yazdırır ve derleme betiğinizde sınayabileceğiniz bir çıkış kodu ayarlar. Kodlar şöyledir: 0 başarı, 1 hata, 2 geçersiz lisans, 3 geçersiz anahtar, 4 geçersiz yapılandırma dosyası, 5 geçersiz girdi dosyası, 6 geçersiz çıktı dosyası ve 7 belirtim geçerli bir OpenAPI 3 belgesine dönüştürülemedi. Hatalar her zaman standart hataya gider.

Üretilen metot, TsgcOpenAPIResponse sınıfından türeyen bir yanıt nesnesi döndürür. Önce IsSuccessful değerini okuyun. False olduğunda ResponseError iletiyi, ResponseCode ise HTTP durumunu taşır. Yanıt nesnesini işiniz bittiğinde serbest bırakın; pakette gelen demo bunu bir try finally içinde yapar.

Üretilen istemci çalışmaz. sgcHTTP_OpenAPI_Client.pas dosyasının tüm arayüzünü saran SGC_HTTP_OPENAPI, ürünün sgcVer.inc dosyasının 702. satırında bir {$IFNDEF BCB} içinde tanımlanır; bu nedenle C++Builder altında o unit hiçbir şeye derlenmez ve üretilen kodun temel sınıfı olmaz. Delphi için üretin.

Üretilen kod Delphi 7 ve sonrasını hedefler. Türlü yanıt nesneleri XE7 veya üzerini gerektirir ve pakette gelen demo bunu {$IF CompilerVersion >= 28.0} ile açıkça belirtir: çizginin üstünde türlü alanları olan bir yanıt nesnesi, altında aynı metot düz bir dize döndürür. Projeniz ikisinde de derlenmek zorundaysa korumayı tutun.

Evet. -s verin; üretici bir istemci yerine kod öncelikli öznitelikler içeren bir sunucu iskeleti üretir. sgcOpenAPI olarak gelen derleme, sgcVer.inc dosyasının 11. satırında SGC_HTTP_OPENAPI_SERVER tanımlar; böylece sunucu tarafı her lisansta bulunur. Demos\30.Server altında iki sunucu demosu gelir.

Siz istemedikçe hayır. YAML yerel olarak okunur ve Swagger 2.0 belgesi yerel olarak OpenAPI 3'e dönüştürülür. Varsayılan olarak kapalı olan -r anahtarı, converter.swagger.io adresindeki genel dönüştürücüye geri dönüşe izin verir ve yardım metni bunun dosyanın tamamını eSeGeCe'nin denetlemediği bir sunucuya yüklediğini açıkça söyler. Gizli olan her şey için kapalı bırakın.

sgcOpenAPI beş dakikada