Ako pracovať s API aplikácie tretej strany. Klasifikácia motorových olejov podľa API. Plány vývoja API

Tento krátky termín je dobre známy každému, kto sa nejakým spôsobom stretol s vývojom. Ale nie každý chápe, čo presne to znamená a prečo je to potrebné. Vývojár Peter Gazarov hovoril o API jednoduchými slovami vo svojom blogu.

Skratka API znamená „Application Programming Interface“ (rozhranie pre programovanie aplikácií, rozhranie pre programovanie aplikácií). Väčšina veľkých spoločností v určitej fáze vyvíja API pre klientov alebo pre vnútorné použitie. Aby ste pochopili, ako a ako sa API používa vo vývoji a podnikaní, musíte najprv pochopiť, ako funguje World Wide Web.

World Wide Web a vzdialené servery

WWW si možno predstaviť ako obrovskú sieť prepojených serverov, ktoré ukladajú každú stránku. bežný notebook môže byť premenený na server schopný obsluhovať celú lokalitu v sieti a lokálne servery vývojári používajú na vytváranie stránok pred ich otvorením širokému okruhu používateľov.

Pri písaní do panela s adresou prehliadača www.facebook.com na vzdialený server Facebook sa odošle zodpovedajúca požiadavka. Keď prehliadač dostane odpoveď, interpretuje kód a vykreslí stránku.

Zakaždým, keď používateľ navštívi stránku na webe, interaguje s API vzdialeného servera. API je časť servera, ktorá prijíma požiadavky a odosiela odpovede.

API ako spôsob, ako slúžiť zákazníkom

Mnoho spoločností ponúka API ako hotový produkt. Napríklad Weather Underground predáva prístup k svojmu API údajov o počasí.

Scenár použitia: na stránke malej firmy je formulár na objednávanie stretnutí pre klientov. Spoločnosť chce do neho vložiť Google Kalendár, aby zákazníci mohli automaticky vytvoriť udalosť a vyplniť podrobnosti o nadchádzajúcom stretnutí.

Aplikácia API: cieľ – server lokality by mal priamo kontaktovať server Google so žiadosťou o vytvorenie udalosti so zadanými podrobnosťami, prijať odpoveď od spoločnosti Google, spracovať ju a odovzdať príslušné informácie prehliadaču, napríklad správu s potvrdením používateľovi .

Alternatívne môže prehliadač odoslať požiadavku na serverové API Google a obísť server spoločnosti.

Ako API Kalendár Google odlišné od API akéhokoľvek iného vzdialeného servera v sieti?

Technicky je rozdiel vo formáte požiadavky a odpovede. Na vygenerovanie kompletnej webovej stránky prehliadač očakáva odpoveď v značkovacom jazyku HTML, zatiaľ čo rozhranie Google Calendar API vráti iba údaje vo formáte ako JSON.

Ak požiadavku na API zadáva server webovej stránky spoločnosti, potom je to klient (rovnako ako klient je prehliadač, keď používateľ otvorí webovú stránku).

Vďaka API dostane používateľ možnosť vykonať akciu bez toho, aby opustil web spoločnosti.

Väčšina moderných webových stránok používa aspoň niekoľko rozhraní API tretích strán. Mnohé úlohy už ponúkajú hotové riešenia vývojárov tretích stránči už ide o knižnicu alebo službu. Často je jednoduchšie a spoľahlivejšie uchýliť sa k hotovému riešeniu.

Mnoho vývojárov distribuuje aplikáciu na niekoľko serverov, ktoré navzájom spolupracujú pomocou API. Servery, ktoré vykonávajú pomocnú funkciu vo vzťahu k hlavnému aplikačnému serveru, sa nazývajú mikroslužby.

Keď teda spoločnosť ponúka svojim používateľom rozhranie API, znamená to jednoducho, že vytvorila sériu špeciálnych adries URL, ktoré vracajú údaje iba ako odpoveď.

Takéto požiadavky možno často odosielať prostredníctvom prehliadača. Keďže prenos dát cez HTTP je v textovej forme, prehliadač vždy dokáže zobraziť odpoveď. Napríklad prostredníctvom prehliadača môžete priamo pristupovať k GitHub API (https://api.github.com/users/petrgazarov) a bez prístupového tokenu a získať nasledujúcu odpoveď vo formáte JSON:

Prehliadač perfektne zobrazuje odpoveď JSON, ktorú je možné vložiť do kódu. Stačí jednoducho extrahovať údaje z takéhoto textu, aby ste ich mohli použiť podľa vlastného uváženia.

Niekoľko ďalších príkladov API

Slovo „aplikácia“ (aplikovaná, aplikácia) môže byť použité v rôznych významoch. V kontexte API to znamená:

• softvér so špecifickou funkciou,
• server ako celok, aplikácia ako celok alebo len samostatná časť aplikácie.

Písmeno „A“ v anglickej skratke môže nahradiť akýkoľvek softvér, ktorý sa dá jasne odlíšiť od prostredia a môže mať aj nejaký druh API. Napríklad, keď vývojár implementuje do kódu knižnicu tretej strany, stane sa súčasťou celej aplikácie. Keďže ide o samostatný softvér, knižnica bude mať nejaký druh rozhrania API, ktoré jej umožní interakciu so zvyškom kódu aplikácie.

V objektovo orientovanom dizajne je kód reprezentovaný ako kolekcia objektov. V aplikácii môžu byť stovky takýchto objektov vzájomne interagujúcich. Každý z nich má svoje API – sadu verejnosti vlastnosti a metódy interakcie s inými objektmi v aplikácii. Objekty môžu mať tiež súkromné, interná logika, ktorá je skrytá pred okolím a nie je API.

Systém klasifikácie motorových olejov API () bol vytvorený v roku 1969. Podľa systému API sú stanovené tri prevádzkové kategórie (tri riadky) účelu a kvality motorových olejov:
S (služba)- pozostáva z kategórií kvality motorových olejov pre benzínové motory v chronologickom poradí.
C (komerčné)- pozostáva z kategórií kvality a účelu olejov pre dieselové motory v chronologickom poradí.
EC (Úspora energie)- energeticky úsporné oleje. Nový riadok vysokokvalitné oleje, pozostávajúce z nízkoviskóznych, ľahko tečúcich olejov, ktoré znižujú spotrebu paliva podľa výsledkov testov pre benzínové motory.

Každá nová trieda má priradené ďalšie písmeno abecedy. Univerzálne oleje pre benzínové a naftové motory sú označené dvoma symbolmi zodpovedajúcich kategórií: prvý symbol je hlavný a druhý označuje možnosť použitia tohto oleja pre iný typ motora. Príklad: API SM/CF.

Triedy kvality API pre benzínové motory

API triedy SN- schválené 1.10.2010.
Hlavným rozdielom medzi API SN a predchádzajúcimi klasifikáciami API je obmedzenie obsahu fosforu kvôli kompatibilite moderné systémy neutralizácia výfukových plynov, ako aj komplexná úspora energie. To znamená, že oleje klasifikované podľa API SN budú približne zodpovedať ACEA C2, C3, C4, bez korekcie na viskozitu pri vysokej teplote.

API triedy SM- Schválené 30. novembra 2004.
Motorové oleje pre moderné benzínové (viacventilové, preplňované) motory. V porovnaní s triedou SL musia mať motorové oleje, ktoré spĺňajú požiadavky API SM, vyššiu úroveň ochrany proti oxidácii a predčasnému opotrebovaniu častí motora. Okrem toho sa zvýšili normy týkajúce sa vlastností oleja pri nízkych teplotách. Motorové oleje tejto triedy môžu byť certifikované podľa triedy energetickej účinnosti ILSAC.
Motorové oleje, ktoré spĺňajú požiadavky API SL, SM môžu byť použité v prípadoch, keď je výrobcom vozidla odporúčaná trieda SJ alebo staršia.

API triedy SL- motorové oleje pre motory automobilov vyrobených po roku 2000.
V súlade s požiadavkami výrobcov automobilov sa motorové oleje tejto triedy používajú vo viacventilových, turbodúchadlom preplňovaných motoroch poháňaných chudobnými palivovými zmesami, ktoré spĺňajú moderné zvýšené ekologické požiadavky, ako aj úsporu energie. Oleje, ktoré spĺňajú požiadavky API SL, môžu byť použité v prípadoch, keď je trieda SJ alebo staršia výrobcom odporúčaná.

Trieda API SJ- motorové oleje na použitie v benzínových motoroch od uvedenia na trh v roku 1996.
Táto trieda popisuje motorové oleje, ktoré sa používajú v benzínových motoroch od roku 1996. Motorové oleje tejto triedy sú určené na použitie v benzínových motoroch osobných a športových automobilov, minibusov a ľahkých nákladných vozidiel, ktoré sú servisované v súlade s požiadavkami výrobcov automobilov. SJ má rovnaké minimálne štandardy ako SH a ďalšie požiadavky na tvorbu uhlíka a prevádzku pri nízkych teplotách. Motorové oleje spĺňajúce požiadavky API SJ sa môžu použiť tam, kde výrobca vozidla odporúča SH alebo skorší.

API trieda SH- motorové oleje pre benzínové motory od uvedenia na trh v roku 1994.
Trieda bola prijatá v roku 1992 pre motorové oleje odporúčané od roku 1993. Táto trieda sa vyznačuje vyššími požiadavkami ako trieda SG a bola vyvinutá ako náhrada za triedu SG, aby sa zlepšili protikarbónové, antioxidačné vlastnosti olejov a olejov proti opotrebovaniu. zvýšená ochrana proti korózii. Motorové oleje tejto triedy sú určené na použitie v benzínových motoroch osobných automobilov, mikrobusov a ľahkých nákladných vozidiel v súlade s odporúčaniami ich výrobcov. Motorové oleje tejto triedy boli testované v súlade s požiadavkami asociácie chemických výrobcov (CMA). Motorové oleje tejto triedy možno použiť, ak výrobca vozidla odporúča triedu SG alebo staršiu.

API triedy SG- motorové oleje pre benzínové motory od uvedenia na trh v roku 1989.
Určené pre použitie v benzínových motoroch osobných automobilov, mikrobusov a ľahkých nákladných automobilov. Motorové oleje tejto triedy majú vlastnosti, ktoré v porovnaní s predchádzajúcimi triedami poskytujú zlepšenú ochranu proti usadzovaniu uhlíka, oxidácii oleja a opotrebovaniu motora a tiež obsahujú prísady, ktoré chránia pred hrdzou a koróziou vnútorných častí motora. Motorové oleje triedy SG spĺňajú požiadavky API CC na oleje pre dieselové motory a možno ich použiť tam, kde sa odporúčajú triedy SF, SE, SF/CC alebo SE/CC.

API trieda SF- motorové oleje pre benzínové motory od roku 1980 (zastaraná trieda).
Tieto motorové oleje sa používali v benzínových motoroch vyrobených v rokoch 1980-1989 v súlade s odporúčaniami a pokynmi výrobcu motora. Poskytuje zvýšenú odolnosť proti oxidácii, zlepšenú ochranu proti opotrebovaniu oproti základovým olejom SE a lepšiu ochranu proti kalu, hrdzi a korózii. Motorové oleje triedy SF by sa mohli použiť ako náhrada za predchádzajúce triedy SE, SD alebo SC.

trieda API SE- motorové oleje pre benzínové motory vyrábané od roku 1972 (zastaraná trieda). Tieto motorové oleje sa používali v benzínových motoroch modelov 1972-79, ako aj niektorých modelov z roku 1971. Dodatočná ochrana v porovnaní s motorovými olejmi SC a SD a môžu sa použiť ako náhrada za tieto kategórie.

Trieda SD API- motorové oleje na použitie v benzínových motoroch od roku 1968 (zastaraná trieda). Motorové oleje tejto triedy sa používali v benzínových motoroch osobných a niektorých nákladných automobilov vyrobených v rokoch 1968-70, ako aj niektorých modelov v roku 1971 a neskôr. Vylepšená ochrana v porovnaní s motorovými olejmi SC, tiež sa používa len vtedy, keď to odporúča výrobca motora.

API triedy SC- motorové oleje pre benzínové motory od roku 1964 (zastaraná trieda). Zvyčajne sa používali v motoroch osobných a niektorých nákladných automobilov vyrobených v rokoch 1964-1967. Znížte vysoko a nízkoteplotné usadeniny, opotrebenie a ochranu proti korózii.

API triedy SB- motorové oleje pre benzínové motory s nízkym výkonom (zastaraná trieda). Motorové oleje z 30-tych rokov 20. storočia, ktoré poskytovali pomerne ľahkú ochranu proti opotrebovaniu a oxidácii, ako aj antikoróznu ochranu ložísk v motoroch prevádzkovaných v podmienkach mierneho zaťaženia. Motorové oleje tejto triedy sa môžu používať iba vtedy, ak sú výslovne odporúčané výrobcom motora.

API triedy SA- motorové oleje pre benzínové a naftové motory. Zastaraná trieda olejov na použitie v starých motoroch pracujúcich v podmienkach a režimoch, v ktorých nie je potrebná ochrana dielov prísadami. Motorové oleje tejto triedy sa môžu používať iba vtedy, ak sú odporúčané výrobcom motora.

Triedy kvality API pre dieselové motory

API triedy CJ-4- účinnosť od 1.10.2006.
Táto trieda je navrhnutá špeciálne pre vysokovýkonné motory. Spĺňa kľúčové požiadavky na emisie NOx a pevných častíc pre motory roku 2007. Pre oleje CJ-4 sú zavedené limity pre niektoré ukazovatele: obsah popola je nižší ako 1,0 %, síra 0,4 %, fosfor 0,12 %.
Nová klasifikácia vyhovuje požiadavkám predchádzajúcich kategórií API CI-4 PLUS, CI-4, ale zavádza významné zmeny požiadaviek v reakcii na potreby nových motorov, ktoré spĺňajú nové emisné normy z roku 2007 a novšie.

API Trieda CI-4 (CI-4 PLUS)- nová prevádzková trieda motorových olejov pre dieselové motory. V porovnaní s API CI-4 sú zvýšené požiadavky na špecifický obsah sadzí, ako aj prchavosť a vysokoteplotnú oxidáciu. Pri certifikácii v tejto klasifikácii musí byť motorový olej testovaný v sedemnástich testoch motora.

API triedy CI-4- trieda bola zavedená v roku 2002.
Tieto motorové oleje sa používajú v moderných dieselových motoroch s rôzne druhy injekcia a boost. Motorový olej, ktorý spĺňa túto triedu, musí obsahovať vhodné detergentné a dispergačné prísady a v porovnaní s triedou CH-4 má zvýšenú odolnosť proti tepelnej oxidácii, ako aj vyššie dispergačné vlastnosti. Okrem toho takéto motorové oleje poskytujú významné zníženie odpadu z motorového oleja znížením prchavosti a znížením vyparovania pri prevádzkových teplotách až do 370 °C pod vplyvom plynov. Sprísnili sa aj požiadavky na čerpateľnosť za studena, zvýšil sa zdroj medzier, tolerancií a tesnení motora zlepšením tekutosti motorového oleja.
Trieda API CI-4 bola zavedená v súvislosti so vznikom nových prísnejších požiadaviek na ekológiu a toxicitu výfukových plynov, ktoré platia pre motory vyrobené od 1. októbra 2002.

API trieda CH-4- účinnosť od 1.12.1998.
Motorové oleje tejto triedy sa používajú v štvortaktných dieselových motoroch, ktoré pracujú vo vysokých otáčkach a spĺňajú požiadavky emisných noriem a noriem z roku 1998.
Motorové oleje API CH-4 spĺňajú pomerne prísne požiadavky amerických aj európskych výrobcov dieselových motorov. Požiadavky triedy sú špeciálne navrhnuté pre použitie v motoroch poháňaných vysokokvalitnými palivami so špecifickým obsahom síry do 0,5 %. Zároveň na rozdiel od triedy API CG-4 je zdroj týchto motorových olejov menej citlivý na používanie motorovej nafty s obsahom síry viac ako 0,5%, čo je obzvlášť dôležité pre krajiny Južnej Ameriky, Ázie. a Afrika.
Motorové oleje API CH-4 spĺňajú zvýšené požiadavky a musia obsahovať prísady, ktoré účinnejšie zabraňujú opotrebovaniu ventilov a tvorbe karbónových usadenín na vnútorných povrchoch. Môžu byť použité ako náhrada motorových olejov API CD, API CE, API CF-4 a API CG-4 v súlade s odporúčaniami výrobcu motora.

API triedy CG-4- trieda bola predstavená v roku 1995.
Motorové oleje tejto triedy sa odporúčajú pre štvortaktné naftové motory autobusov, nákladných vozidiel a traktorov hlavného a mimohlavného typu, ktoré sú prevádzkované v režime vysokého zaťaženia a vysokej rýchlosti. Motorový olej API CG-4 je vhodný pre motory, ktoré používajú vysokokvalitné palivá so špecifickým obsahom síry maximálne 0,05%, ako aj pre motory, pre ktoré nie sú špeciálne požiadavky na kvalitu paliva (špecifický obsah síry môže dosiahnuť 0,5% ).
Motorové oleje s certifikáciou API CG-4 by mali účinnejšie predchádzať opotrebovaniu vnútorných častí motora, tvorbe usadenín na vnútorných povrchoch a piestoch, oxidácii, peneniu a tvorbe sadzí (tieto vlastnosti sú potrebné najmä pre motory moderných diaľkových autobusov a traktorov). ).
Trieda API CG-4 vznikla v súvislosti so schválením nových požiadaviek a noriem v USA na ekológiu a toxicitu výfukových plynov (revidovaná v roku 1994). Motorové oleje tejto triedy možno použiť v motoroch, pre ktoré sa odporúčajú triedy API CD, API CE a API CF-4. Hlavnou nevýhodou, ktorá obmedzuje masové používanie motorových olejov tejto triedy, napríklad vo východnej Európe a Ázii, je značná závislosť zdroja motorového oleja od kvality použitého paliva.

API trieda CF-2 (CF-II)- motorové oleje určené na použitie v dvojtaktných dieselových motoroch, ktoré pracujú v náročných podmienkach.
Trieda bola predstavená v roku 1994. Motorové oleje tejto triedy sa zvyčajne používajú v dvojtaktných dieselových motoroch, ktoré pracujú pod zvýšeným zaťažením. Oleje API CF-2 musia obsahovať prísady, ktoré poskytujú zvýšenú výkonovú ochranu proti opotrebovaniu vnútorných častí motora, ako sú valce a krúžky. Okrem toho musia tieto motorové oleje zabrániť hromadeniu usadenín na vnútorných povrchoch motora (vylepšená funkcia čistenia).
Motorový olej certifikovaný podľa API CF-2 má vylepšené vlastnosti a možno ho použiť namiesto starších podobných olejov podľa odporúčania výrobcu.

API triedy CF-4- motorové oleje na použitie v štvortaktných dieselových motoroch od uvedenia na trh v roku 1990.
Motorové oleje tejto triedy sa môžu používať v štvortaktných dieselových motoroch, ktorých prevádzkové podmienky sú spojené s vysokorýchlostnými režimami. Pre takéto podmienky požiadavky na kvalitu oleja presahujú možnosti triedy CE, takže namiesto olejov triedy CE možno použiť motorové oleje CF-4 (ak existujú vhodné odporúčania od výrobcu motora).
Motorové oleje API CF-4 musia obsahovať vhodné prísady, ktoré zabezpečia zníženie vyhorenia automobilového oleja, ako aj ochranu pred usadeninami uhlíka v skupine piestov. Hlavným účelom motorových olejov tejto triedy je použitie v dieselových motoroch ťažkých traktorov a iných vozidiel, ktoré sa používajú na dlhé cesty po diaľniciach.
Okrem toho sa týmto motorovým olejom niekedy priraďuje dvojitá trieda API CF-4/S. V tomto prípade, ak sú k dispozícii príslušné odporúčania od výrobcu motora, môžu byť tieto motorové oleje použité aj v benzínových motoroch.

Trieda API CF (CF-2, CF-4)- motorové oleje pre dieselové motory s nepriamym vstrekovaním. Triedy boli zavedené od roku 1990 do roku 1994. Číslo s pomlčkou znamená dvoj- alebo štvortaktný motor.
Trieda CF popisuje motorové oleje odporúčané na použitie v dieselových motoroch s nepriamym vstrekovaním, ako aj v iných typoch dieselových motorov, ktoré poháňajú palivo. rôzna kvalita vrátane tých, ktoré majú vysoký obsah síry (napríklad viac ako 0,5 % z celkovej hmotnosti).
Motorové oleje s certifikáciou CF obsahujú prísady na zlepšenie prevencie usadenín na piestoch, opotrebovania a korózie medených ložísk (obsahujúcich meď), ktoré sú dôležité pre tieto typy motorov a možno ich čerpať konvenčným spôsobom, ako aj turbodúchadlom alebo kompresorom. Motorové oleje tejto triedy sa môžu používať tam, kde sa odporúča kvalita CD.

Trieda API CE- motorové oleje na použitie v dieselových motoroch od roku 1983 (zastaraná trieda).
Automobilové oleje tejto triedy boli určené na použitie v niektorých vysokovýkonných preplňovaných motoroch, ktoré sa vyznačujú výrazne zvýšenou pracovnou kompresiou. Použitie takýchto olejov bolo povolené pre motory s nízkymi aj vysokými otáčkami hriadeľa.
Motorové oleje API CE sa odporúčajú pre nízko a vysokorýchlostné dieselové motory vyrobené od roku 1983, ktoré pracujú v náročných podmienkach. Za predpokladu dostupnosti príslušných odporúčaní od výrobcu motora by sa tieto motorové oleje mohli používať aj v motoroch, pre ktoré boli odporúčané motorové oleje triedy CD.

API triedy CD-II- motorové oleje na použitie vo vysokovýkonných dieselových motoroch s dvojtaktným pracovným cyklom (zastaraná trieda).
Trieda bola predstavená v roku 1985 na použitie v dvojtaktných dieselových motoroch a je v skutočnosti evolučným vývojom predchádzajúcej triedy API CD. Hlavným účelom použitia takýchto motorových olejov bolo použitie v ťažkých výkonných dieselových motoroch, ktoré boli inštalované najmä na poľnohospodárskych strojoch. Motorové oleje tejto triedy spĺňajú všetky výkonnostné štandardy predchádzajúcej triedy CD, navyše sa výrazne zvýšili požiadavky na vysoko účinnú ochranu motora pred karbónovými usadeninami a opotrebovaním.

Trieda CD API- motorové oleje pre dieselové motory so zvýšeným výkonom, ktoré sa používali v poľnohospodárskych strojoch (zastaraná trieda). Trieda bola predstavená v roku 1955 na všeobecné použitie v niektorých dieselových motoroch, atmosférických aj preplňovaných, so zvýšenou kompresiou valcov, kde je nevyhnutná účinná ochrana proti usadzovaniu uhlíka a opotrebovaniu. Motorové oleje tejto triedy by sa mohli použiť v prípadoch, keď výrobca motora nepredložil dodatočné požiadavky na kvalitu paliva (vrátane paliva s vysokým obsahom síry).
Motorové oleje API CD mali v porovnaní s predchádzajúcimi triedami poskytovať zvýšenú ochranu proti korózii ložísk a vysokoteplotným sadziam v dieselových motoroch. Motorové oleje v tejto triede sa často nazývali „Caterpillar Series 3“, pretože spĺňali požiadavky certifikácie Superior Lubricants (Series 3) vyvinutej spoločnosťou Caterpillar Tractor Company.

API triedy CC- motorové oleje pre dieselové motory, ktoré sú prevádzkované v podmienkach stredného zaťaženia (zastaraná trieda).
Trieda bola predstavená v roku 1961 pre použitie v niektorých motoroch, atmosférických aj preplňovaných, ktoré sa vyznačovali zvýšenou kompresiou. Motorové oleje tejto triedy boli odporúčané pre motory, ktoré boli prevádzkované v režime mierneho a vysokého zaťaženia.
Okrem toho v súlade s odporúčaniami výrobcu motora by sa takéto motorové oleje mohli používať v niektorých výkonných benzínových motoroch.
V porovnaní s predchádzajúcimi triedami sa od motorových olejov API CC vyžadovalo, aby poskytovali vyššiu úroveň ochrany proti usadeninám pri vysokých teplotách a korózii ložísk v dieselových motoroch, ako aj pred hrdzou, koróziou a usadeninami pri nízkych teplotách v benzínových motoroch.

API triedy CB- motorové oleje pre dieselové motory pracujúce so stredným zaťažením (zastaraná trieda).
Trieda bola schválená v roku 1949 ako evolučný vývoj triedy CA s použitím paliva s vysokým obsahom síry bez špeciálnych požiadaviek na kvalitu. Motorové oleje API CB boli určené aj na použitie v preplňovaných motoroch, ktoré boli prevádzkované v ľahkých a miernych podmienkach. Táto trieda bola často označovaná ako „motorové oleje z prílohy 1“, aby sa indikovala zhoda s vojenským predpisom MIL-L-2104A, príloha 1.

API triedy CA- motorové oleje pre málo zaťažované dieselové motory (zastaraná trieda).
Automobilové oleje tejto triedy sú určené na použitie v dieselových motoroch pracujúcich v ľahkých a miernych podmienkach na vysokokvalitnú motorovú naftu. V súlade s odporúčaniami výrobcov automobilov ich možno použiť aj v niektorých benzínových motoroch, ktoré sú prevádzkované v miernych podmienkach.
Trieda bola široko používaná v 40. a 50. rokoch minulého storočia a v moderných podmienkach sa nedá použiť, pokiaľ to nevyžaduje výrobca motora.
Motorové oleje API CA musia mať vlastnosti, ktoré poskytujú ochranu proti usadzovaniu karbónu na piestnych krúžkoch, ako aj proti korózii ložísk v preplňovaných motoroch, na ktoré nie sú kladené špeciálne požiadavky na kvalitu použitého paliva.

V tomto príspevku som sa pokúsil zhromaždiť informácie, ktoré môžu byť užitočné pre testerov, ktorí chcú vedieť, čo je API. Dúfam, že ľudia, ktorí majú skúsenosti s testovaním API, nájdu niečo užitočné aj pre seba. No, alebo aspoň pomôžte nájsť chyby v mojom článku :)
Čo je API

API (Application Programming Interface) - súbor hotových tried, procedúr, funkcií, štruktúr a konštánt poskytovaných aplikáciou (knižnicou, službou) na použitie v externých softvérových produktoch (Wikipedia).

Inými slovami, API nám dáva možnosť využiť vývoj iných ľudí pre naše vlastné účely. Prvýkrát som narazil na API využívajúce ako príklad Windows API. Ide o súbor funkcií, ktoré môže využívať každá aplikácia spustená na danom OS. Napríklad môže použiť štandardné funkcie na kreslenie rozhrania.

Moderné rozhrania API majú často podobu webových služieb, ktoré používateľom (ľudom aj iným webovým službám) poskytujú určitý druh informácií. Postup výmeny informácií a formát prenosu údajov sú zvyčajne štruktúrované tak, aby obe strany vedeli, ako na seba navzájom pôsobiť.

Na stránke https://dev.hh.ru/ (presnejšie https://github.com/hhru/api/blob/master/docs/general.md) nájdete popis, ako klienti HeadHunter API a služby navzájom interagujú. Napríklad citát zo stránky:

• Všetky API fungujú cez protokol HTTPS.
• Autorizácia sa vykonáva pomocou protokolu OAuth2.
• Všetky údaje sú dostupné iba vo formáte JSON.
• Základná adresa URL — https://api.hh.ru/
• Dátumy sú naformátované podľa ISO 8601: RRRR-MM-DDThh:mm:ss±hhmm

Formáty prenosu dát

Existuje mnoho formátov údajov, ktoré používatelia používajú na interakciu s rozhraním API. Napríklad známy XML. Alebo JSON - ľahký a nekomplikovaný formát, ktorý vyzerá takto:

( "id": "0001", "type": "donut", "name": "Torta", "image": ( "url": "images/0001.jpg", "width": 200, "height ": 200)) P o ss V nižšie uvedených odkazoch môžete vidieť odpovede pochádzajúce z MediaWikiAPI , v rôznych formátoch :

JSON:https://en.wikipedia.org/w/api.php?action=query&titles=Albert%20Einstein&prop=info&format=jsonfm
XML: https://en.wikipedia.org/w/api.php?action=query&titles=Albert%20Einstein&prop=info&format=xmlfm
PHP: https://en.wikipedia.org/w/api.php?action=query&titles=Albert%20Einstein&prop=info&format=php ( opatrne, stať s hojdaním súbor)

http g lagos

Zvyčajne P Pri prístupe k webovému APIpoužitím Požiadavky HTTP sa odosielajú . Pretoaspoň stručne o štandardné metódy, ktoré môžu byť obsiahnuté v HTTP požiadavka . Tieto metódy tiež nazývané HTTP slovesá :

• GET. Asi najobľúbenejší typ žiadosť. Používa sa na príjem alebo čítanie údajov.
• PUT. Obvyklé n oh a spo Používa sa na aktualizáciu zdroja .
• POST. Zvyčajne sa používa na vytvorenie nového zdroja.
• VYMAZAŤ. Vymaže údaje.
• A ďalšie

Ak chceme aktualizovať zdroj - môžeme poslať požiadavku PUT:
PUT http://www.example.com/customers/12345/orders/98765

Normálne požiadavky GET môžu byť odoslané webovým prehliadačom. Odosielanie iných typov žiadostí môže vyžadovať skriptovacie jazyky alebo špeciálne nástroje(viac o tom nižšie).

O HTTP metódy možno prečítať podrobnejšie pri na W iki.

http na ódy odpovedí

Server môže odosielať rôzne kódy ako odpoveď na požiadavky používateľov. Môžu to byť chybové kódy alebo jednoducho kódy informujúce používateľov o stave servera. Detailný popis nájdete opäť na wiki.

Najznámejšie kódy sú 4xx (problémy na strane klienta) a 5xx (problémy na strane servera). O tom, ktoré kódy sa v danej situácii vrátia, rozhodujú samotní vývojári API. Napríklad API webovej stránky Odnoklassniki vracia kódy, ktorých popis nájdete na stránke https://apiok.ru/wiki/pages/viewpage.action?pageId=77824003 .

Okrem toho vám odporúčam, aby ste si vypočuli pieseň Request-Response - jednoduchá a jasná o kódoch vrátených v požiadavkách HTTP (opatrne, repchik :)).

REST API - to je ideológia príspevku rojenie API, čo znamenáPrevod reprezentačného štátu API. Je založený na nasledujúcich princípoch formulovaných jeho tvorcom , Roy Fielding:

1. Architektúra klient-server
2. Bezstavový server
3. cacheability
4. Viacvrstvová štruktúra
5. Jediné rozhranie
6. Kód na požiadanie

Windows API - sada funkcií operačný systém

Skratka API sa mnohým začínajúcim programátorom zdá veľmi tajomná až desivá. V skutočnosti je aplikačné programové rozhranie (API) len nejaký hotový súbor funkcií, ktoré môžu vývojári aplikácií používať. Vo všeobecnosti je tento koncept ekvivalentný tomu, čo sa kedysi častejšie nazývalo knižnica podprogramov. API sa však zvyčajne chápe ako špeciálna kategória takýchto knižníc.

Počas vývoja takmer akejkoľvek pomerne zložitej aplikácie (MyApplication) sa pre koncového používateľa vytvorí súbor špecifických interných funkcií, ktoré sa používajú na implementáciu tohto konkrétneho programu, ktorý sa nazýva API MyApplication. Často sa však ukazuje, že tieto funkcie sa dajú efektívne využiť na vytváranie iných aplikácií, vrátane iných programátorov. V tomto prípade sa musia autori na základe stratégie propagácie svojho produktu rozhodnúť, či otvoria prístup k tejto zostave pre externých používateľov alebo nie? Ak je odpoveď áno, v popise softvérového balíka sa ako pozitívna charakteristika objavuje fráza: „Balík obsahuje otvorený súbor funkcií API“ (niekedy však za ďalšie peniaze).

API teda najčastejšie označuje množinu funkcií, ktoré sú súčasťou jednej aplikácie, no zároveň sú dostupné na použitie v iných programoch. Napríklad Excel má okrem rozhrania pre koncového používateľa sadu Excel funkcie API, ktoré možno použiť najmä pri vytváraní aplikácií s VB.

V súlade s tým je Windows API súborom funkcií, ktoré sú súčasťou samotného operačného systému a zároveň sú dostupné pre akúkoľvek inú aplikáciu, vrátane tých, ktoré sú napísané pomocou VB. V tomto ohľade analógia so súpravou systém preruší BIOS/DOS, čo je vlastne DOS API.

Rozdiel je v tom, že skladba funkcií Windows API je na jednej strane oveľa širšia v porovnaní s DOSom, na druhej strane neobsahuje veľa nástrojov na priamu správu počítačových zdrojov, ktoré mali k dispozícii programátorov v predchádzajúcom OS. Okrem toho sa prístup k Windows API vykonáva pomocou bežných procedurálnych volaní a funkcie DOS sa volajú prostredníctvom špeciálnej strojovej inštrukcie procesora, ktorá sa nazýva Interrupt ("prerušenie").

Prečo potrebujete Win API pre programátorov VB

Napriek tomu, že VB má obrovské množstvo funkcií, v procese viac či menej seriózneho vývoja sa ukazuje, že ich schopnosti často nestačia na riešenie potrebných úloh. Zároveň sa začínajúci programátori často začínajú sťažovať na nedostatky VB a premýšľajú o zmene nástrojov, nemajú podozrenie, že ich počítač má obrovskú sadu nástrojov a stačí vedieť, ako ich používať.

Pri oboznámení sa s Win API sa ukazuje, že mnohé vstavané funkcie VB nie sú ničím iným ako volaním príslušných systémových procedúr, ale sú implementované iba vo forme syntaxe. daný jazyk. Vzhľadom na to je potreba použiť rozhranie API určená nasledujúcimi možnosťami:

1. Funkcie API, ktoré sú plne implementované ako vstavané funkcie VB. Niekedy je však v tomto prípade užitočné prejsť na používanie API, pretože to môže niekedy výrazne zlepšiť výkon (najmä kvôli absencii zbytočných konverzií odovzdávaných parametrov).
2. Vstavané funkcie VB implementujú iba špeciálny prípad zodpovedajúcej funkcie API. Toto je pomerne bežná možnosť. Napríklad rozhranie CreateDirectory API je výkonnejšie ako vstavaný príkaz VB MkDir.
3. Obrovské množstvo funkcií API nemá v súčasnej verzii jazyka VB vôbec žiadne analógy. Napríklad nemôžete odstrániť adresár pomocou VB - na to musíte použiť funkciu DeleteDirectory.

Treba tiež zdôrazniť, že niektoré funkcie API (ich podiel na Win API je veľmi malý) nie je možné volať z programov VB z dôvodu množstva jazykových obmedzení, napríklad z dôvodu nedostatočnej možnosti práce s pamäťovými adresami. V niektorých prípadoch však môžu pomôcť netriviálne programovacie techniky (najmä v prípade rovnakých adries).

Osobný názor autora je taký, že namiesto rozširovania z verzie na verziu vstavaných funkcií VB by sme mali dať dobrý popis najpopulárnejšie funkcie API. Zároveň by som chcel vývojárom poradiť, aby nečakali na vzhľad Nová verzia nástroje s pokročilými funkciami, a aby sme sa bližšie pozreli na zloženie existujúceho Win API – je pravdepodobné, že funkcie, ktoré potrebujete, by mohli byť implementované už vo verzii VB 1.0 z roku 1991.

Ako sa naučiť Win API

To nie je až taká jednoduchá otázka, vzhľadom na to, že počet funkcií Win32 API sa odhaduje na cca 10 000 (presné číslo nepozná nikto, ani Microsoft).

VB (verzie 4-6) obsahuje súbor s popisom deklarácií Win API - WIN32API.TXT (viac o jeho použití neskôr). Po prvé ho však možno použiť na získanie informácií o účele konkrétnej funkcie a jej parametroch iba podľa použitých mnemotechnických názvov a po druhé, zoznam funkcií v tomto súbore nie je ani zďaleka úplný. Kedysi (pred siedmimi rokmi) mal VB 3.0 špeciálne súbory pomocníka popisujúce funkcie Win16 API. Avšak už vo verzii 4.0 tieto užitočné informácie s pohodlným rozhraním zmizli.

Komplexné informácie o Win32 API nájdete v systém pomoci Platform Software Development Kit, ktorý sa nachádza najmä na CD MSDN Library, ktoré sú súčasťou VB 5.0 a 6.0 Enterprise Edition a Office 2000 Developer Edition. Nie je však jednoduché nájsť tam potrebné informácie a pochopiť ich. Nehovoriac o tom, že všetky popisy sú tam uvedené vo vzťahu k jazyku C.

Svetovo uznávanou príručkou pre učenie sa programovania API v prostredí VB sú knihy známeho amerického odborníka Daniela Applemana. Jeho séria Dan Appleman's Visual Basic Programmer's Guide to Windows API (pre Win16, Win32, aplikovaná na rôzne verzie VB) je od roku 1993 jedným z bestsellerov pre programátorov VB. VB 5.0 Programmer's Guide to the Win32 API od Dana Applemana, vydaný v roku 1997, priniesol autorovi z USA kamarát, ktorý ho našiel v prvom kníhkupectve v malom provinčnom meste.

Táto kniha má viac ako 1 500 strán a obsahuje všeobecné programovacie techniky VB API, ako aj viac ako 900 funkcií. Sprievodný CD-ROM obsahuje úplný text knihy a všetky príklady programovania, ako aj niekoľko ďalších kapitol, ktoré nie sú súčasťou tlačenej verzie. V roku 1999 vydal Dan Appleman nová kniha Dan Appleman's Win32 API Puzzle Book and Tutorial for Visual Basic Programmers, ktorý obsahuje informácie o ďalších 7600 funkciách (aj keď nie tak rozsiahlych).

Win API a dynamická knižnica (DLL)

Sada Win API je implementovaná ako dynamické knižnice DLL. Ďalej si v skutočnosti povieme o technológii používania DLL v prostredí VB na príklade knižníc, ktoré sú súčasťou Win API. Keď však hovoríme o knižniciach DLL, je potrebné poznamenať niekoľko dôležitých vecí.

V tomto prípade pod DLL rozumieme tradičný variant binárnych dynamických knižníc, ktoré poskytujú priamy prístup aplikácií k potrebným procedúram - podprogramom alebo funkciám (podobne ako pri volaní procedúr vo VB projekte). Takéto knižnice je možné vytvárať pomocou rôznych nástrojov: VC ++, Delphi, Fortran, okrem VB (uvidíme, čo sa objaví vo verzii 7.0) - tá dokáže vytvárať iba ActiveX DLL, ku ktorým sa pristupuje cez rozhranie OLE Automation.

Súbory dynamických knižníc majú zvyčajne príponu .DLL, ale to vôbec nie je potrebné (pre Win16 sa často používala prípona .EXE); Ovládače externých zariadení sú označené .DRV.

Ako sme už uviedli, je dosť ťažké určiť presný počet Windows API a súborov, ktoré ich obsahujú, ale všetky sa nachádzajú v systémovom adresári. V tomto ohľade je lepšie vyzdvihnúť zloženie knižníc zahrnutých v jadre operačného systému a hlavné knižnice s kľúčovými doplnkovými funkciami.

A teraz pár tipov.

Tip 1: Uistite sa, že vaša reklama DL je správne naformátovaná L-postupy

Samotné volanie procedúr DLL v programe vyzerá úplne rovnako ako „bežné“ procedúry Visual Basic, napríklad:

Volať DllName([zoznam argumentov])

Ak však chcete použiť externé funkcie DLL (vrátane Win API), musia byť deklarované v programe pomocou príkazu Declare, ktorý vyzerá takto:

Deklarujte Sub LibProcedureName _ “LibraryName” _ [([ArgumentList])]

Deklarujte FunctionName FunctionName _ Lib "LibraryName" _ [([ArgumentList])]

Tu sú voliteľné prvky operátora uvedené v hranatých zátvorkách, premenné výrazu sú kurzívou, zvyšok slov sú kľúčové slová. Systém nápovedy má celkom dobrý popis syntaxe operátora, takže zatiaľ urobíme len pár bodov.

Externé deklarácie funkcií musia byť umiestnené v sekcii Všeobecné deklarácie modulu. Ak ho umiestnite do modulu formulára, musíte zadať kľúčové slovo Private (táto deklarácia bude dostupná iba v tomto module) - toto je obmedzenie pre všetky procedúry modulu formulára.

Sada Win32 API je implementovaná len ako funkcie (Win16 API malo veľa Sub rutín). Z veľkej časti ide o funkcie typu Long, ktoré najčastejšie vracajú kód dokončenia operácie.

Príkaz Declare sa objavil v MS Basic ešte v časoch DOSu a používal sa aj na deklarovanie interných postupov projektu. Vo Visual Basicu sa to nevyžaduje, keďže deklarácia interných procedúr je automaticky ich deklaráciou Sub alebo Function. Oproti Basic/DOS je v novom popise povinné uviesť názov súboru knižnice, kde sa nachádza požadovaná procedúra. Knižnice Wip API sa nachádzajú v systémovom adresári Windows, takže stačí zadať iba názov súboru. Ak pristupujete k knižnici DLL, ktorá sa nachádza na ľubovoľnom mieste, musíte si zapísať úplnú cestu k tomuto súboru.

Popis príkazu Declare zvyčajne zaberá pomerne veľa miesta a nezmestí sa na jeden riadok v okne kódu. Preto vám odporúčame, aby ste pri písaní aplikácií dodržiavali určitú špecifickú schému zalamovania riadkov, napríklad:

Deklarovať funkciu GetTempPath _ Lib "kernel32" Alias ​​​​"GetTempPathA" _ (ByVal nBufferLength ako dlhý, _ ByVal lpBuffer ako reťazec) ako dlhý

V tomto prípade sú všetky hlavné prvky popisu rozdelené do rôznych riadkov, a preto sú dobre čitateľné.

Tip 2: Buďte obzvlášť opatrní pri práci s funkciami DLL

Používanie Win API a rôznych funkcií DLL výrazne rozširuje funkčnosť VB a často zlepšuje výkon programov. Odmenou za to je však riziko zníženia spoľahlivosti aplikácie, najmä v procese jej ladenia.

Jednou z najdôležitejších výhod prostredia VB je spoľahlivosť procesu vývoja programu: fungujúci pod kontrolou tlmočníka, programový kód teoreticky nemôže narušiť Windows funguje a samotný VB. Programátor nemusí byť veľmi pozorný na správnosť odovzdávania parametrov volaným funkciám - takéto chyby ľahko odhalí samotný interpret buď v procese prekladu kódu alebo počas jeho vykonávania. V najnepríjemnejšom prípade sa režim spracovania jednoducho preruší as uvedením, kde a prečo došlo k chybe.

Priame používanie funkcií Windows API alebo iných knižníc DLL odstraňuje takúto kontrolu nad prenosom údajov a vykonávaním kódu mimo prostredia VB. Preto chyba v prístupe k externým funkciám môže viesť k nefunkčnosti VB aj operačného systému. To platí najmä vo fáze vývoja programu, keď je prítomnosť chýb celkom prirodzená. Aplikáciou širších možností funkcií základnej vrstvy systému teda programátor preberá zodpovednosť za správnosť ich aplikácie.

Problém je umocnený skutočnosťou, že rôzne programovacie jazyky používajú rôzne spôsoby odovzdávania parametrov medzi procedúrami. (Presnejšie, rôzne cesty priechody sú predvolené, pretože mnoho jazykov môže podporovať viacero metód.) Rozhrania Win API sú implementované v C/C++ a používajú konvencie odovzdávania parametrov tohto systému, ktoré sú odlišné od toho, na čo sa používa VB.

V tejto súvislosti je potrebné poznamenať, že objavenie sa analógov funkcií API zabudovaných do VB je odôvodnené práve prispôsobením týchto funkcií syntaxi VB a implementáciou zodpovedajúceho mechanizmu kontroly výmeny údajov. Všimnite si tiež, že vo fáze experimentálneho ladenia aplikácie pri vytváraní spustiteľného modulu je lepšie použiť možnosť kompilácie P-kódu namiesto Native Code (strojový kód). V prvom prípade bude program bežať pod kontrolou tlmočníka – pomalšie ako strojový kód, no spoľahlivejšie z hľadiska možných chybných vplyvov na operačný systém a poskytujúceho pohodlnejší režim na zisťovanie prípadných chýb.

Tip 3: Desať tipov Dana Applemana na spoľahlivé programovanie API vo VB

Používanie funkcie API si vyžaduje starostlivejšie programovanie, pričom sa používajú niektoré z neznámejších metód volania procedúr (v porovnaní s VB). Týmto problémom sa budeme ďalej venovať. A teraz tu je súhrn rád Dana Applemana na túto tému (ich prvá verzia sa objavila už v roku 1993), s niektorými našimi dodatkami a komentármi.

1. Pamätajte na ByVal. Väčšina častá chyba, ktorý sa vykonáva pri prístupe k funkciám API a DLL, je nesprávne použitie kľúčové slovo ByVal: buď to zabudnú dať, alebo naopak, dajú, keď to nie je potrebné.

Tieto príklady ukazujú vplyv príkazu ByVal na odovzdávanie parametrov

Tu je potrebné pripomenúť, že prenos parametrov v akomkoľvek programovacom systéme, vrátane VB, sa vykonáva dvoma hlavnými spôsobmi: odkazom (ByRef) alebo hodnotou (ByVal). V prvom prípade sa odovzdá adresa premennej (táto možnosť sa štandardne používa vo VB), v druhom - jej hodnota. Zásadný rozdiel spočíva v tom, že pomocou referencie sa volajúcemu programu vráti zmenená hodnota odovzdaného parametra.

Aby ste to pochopili, vykonajte experiment pomocou nasledujúcich programov:

Dim v As Integer v = 2 Volanie MyProc(v) MsgBox “v = “ & v Sub MyProc (v As Integer) v = v + 1 End Sub

Keď spustíte tento príklad, dostanete správu s hodnotou premennej rovnajúcou sa 3. Faktom je, že v tomto prípade je adresa premennej v, fyzicky vytvorená vo volajúcom programe, odovzdaná podprogramu MyProc. Teraz zmeňte popis postupu na

Sub MyProc (ByVal v. As Integer)

Výsledkom je, že pri spustení testu dostanete v = 2, pretože procedúre sa odovzdá iba počiatočná hodnota premennej – výsledok operácií na nej vykonaných sa nevracia volajúcemu programu. Režim prechodu podľa hodnoty môžete zmeniť aj pomocou príkazu Call takto:

Sub MyProc (v As Integer) ... Call MyProc((v)) ‘ (v) - zátvorky označujú režim pass-by-value _.

Pri odkaze na interné postupy VB je však použitie kľúčového slova ByVal v príkaze Call zakázané – namiesto toho sa používajú zátvorky. Toto má svoje vysvetlenie.

V klasickom prípade (C, Fortran, Pascal) rozdiel medzi režimami ByRef a ByVal závisí od toho, čo presne je umiestnené na zásobníku výmeny dát – adresa premennej alebo jej hodnota. Basic historicky používa variant softvérovej emulácie ByVal - adresa je vždy na zásobníku, ale len pri prechode hodnotou je na to vytvorená dočasná premenná. Na rozlíšenie medzi týmito dvoma možnosťami (klasická a základná) sa používajú rôzne spôsoby popisu režimu ByVal. Všimnite si, že emulácia režimu ByVal vo VB poskytuje vyššiu spoľahlivosť programu: zámenou formy volania programátor riskuje len to, že sa volajúcemu programu vráti (alebo nevráti) opravená hodnota premennej. V "klasickej" verzii môže takýto zmätok viesť k fatálna chyba keď sa vykoná procedúra (napríklad keď sa namiesto adresy pamäte použije premenná hodnota rovnajúca sa napríklad nule).

Funkcie DLL sú implementované podľa "klasických" princípov, a preto vyžadujú povinný popis spôsobu výmeny údajov s každým z argumentov. Na to slúžia deklarácie funkcií cez popis Declare (presnejšie zoznam odovzdaných argumentov). Najbežnejším spôsobom odovzdávania parametrov funkcii Windows API alebo DLL je použitie kľúčového slova ByVal. Navyše sa dá nastaviť ako v príkaze Declare, tak aj priamo pri volaní funkcie.

Dôsledky nesprávneho odovzdávania parametrov sa dajú ľahko predvídať. Ak dostanete zjavne neplatnú adresu, dostanete správu GPF (General Protection Fault). Ak funkcia dostane hodnotu, ktorá sa zhoduje s platnou adresou, potom funkcia API prelezie do oblasti niekoho iného (napríklad do jadra Windowsu) so všetkými z toho vyplývajúcimi katastrofálnymi následkami.

2. Skontrolujte typ odovzdaných parametrov. Rovnako dôležitý je správny počet a typ odovzdaných parametrov. Argumenty deklarované v Declare sa musia zhodovať s očakávanými parametrami vo funkcii API. Najčastejší prípad chyby pri odovzdávaní parametrov súvisí s rozdielom medzi hodnotou NULL a reťazcom s nulovou dĺžkou – nezabudnite, že nejde o to isté.

3. Skontrolujte typ návratu.

VB je dosť tolerantný k nesúladu typu návratu. hodnotová funkcia, pretože číselné hodnoty sa zvyčajne vracajú cez registre, nie cez zásobník. Nasledujúce pravidlá pomôžu určiť správnu hodnotu vrátenú funkciou API:

• Funkcia DLL, ktorá nevracia hodnotu (podobne ako void v 'C'), musí byť deklarovaná ako VB Sub.
• Funkcia API, ktorá vracia celočíselné hodnoty (Integer alebo Long), môže byť definovaná ako Sub alebo Funkcia, ktorá vracia hodnotu príslušného typu.
• žiadna z funkcií API nevracia čísla s pohyblivou rádovou čiarkou, ale niektoré knižnice DLL môžu vrátiť takýto typ údajov.

4. Konštrukciu "Ako každý" používajte veľmi opatrne. Mnohé funkcie Windows API majú schopnosť akceptovať parametre rôznych typov a použiť konštrukciu As Any (interpretácia typu sa vykonáva v závislosti od hodnoty ostatných odovzdaných parametrov).

Dobrým riešením v tomto prípade môže byť použitie viacerých aliasov funkcií (Alias) s vytvorením dvoch alebo viacerých deklarácií pre tú istú funkciu, pričom každá z deklarácií špecifikuje parametre určitého typu.

5. Nezabudnite inicializovať reťazce. V rozhraní Win API je veľa funkcií, ktoré vracajú informácie načítaním údajov do vyrovnávacích pamätí reťazcov odovzdaných ako parameter. Zdá sa, že vo vašom programe robíte všetko správne: nezabudnite na ByVal, správne odovzdajte parametre funkcii. Systém Windows však nemôže skontrolovať, aká veľká je veľkosť pamäte pridelenej pre reťazec. Riadok musí byť dostatočne veľký, aby sa doň zmestili všetky údaje, ktoré je možné doň umiestniť. Je zodpovednosťou programátora VB rezervovať vyrovnávaciu pamäť správnej veľkosti.

Upozorňujeme, že v 32-bitovom systéme Windows sa reťazce konvertujú z Unicode (dvojbajtové kódovanie) na ANSI (jednobajtové) a naopak, pričom sa zohľadňujú národné nastavenia systému. Preto je na rezervovanie vyrovnávacích pamätí niekedy vhodnejšie použiť bajtové polia namiesto reťazcových premenných. (Viac o tom bude diskutované nižšie.)

Funkcie Win API vám častejšie umožňujú definovať maximálnu veľkosť bloku sami. Najmä to niekedy vyžaduje volanie inej funkcie API, ktorá „vyzve“ veľkosť bloku. Napríklad GetWindowTextLength vám umožňuje určiť veľkosť reťazca potrebného na prispôsobenie názvu okna vráteného funkciou GetWindowText. V tomto prípade systém Windows zabezpečí, aby ste neprekročili hranice.

6. Uistite sa, že používate Option Explicit.

7. Starostlivo skontrolujte hodnoty parametrov a návratové hodnoty. VB má dobré možnosti typovej kontroly. To znamená, že keď sa pokúsite odovzdať neplatný parameter funkcii VB, najhoršia vec, ktorá sa môže stať, je, že dostanete od VB chybové hlásenie. Ale tento mechanizmus, žiaľ, nefunguje pri prístupe k funkciám Windows API.

Windows 9x má vylepšený systém kontroly parametrov pre väčšinu funkcií API. Prítomnosť chyby v dátach teda zvyčajne nespôsobuje fatálnu chybu, no nie je také ľahké určiť, čo ju spôsobilo.

Tu vám môžeme odporučiť, aby ste použili niekoľko spôsobov ladenia tohto typu chyby:

• použite ladenie krok za krokom alebo príkaz Debug.Print na kontrolu každého podozrivého volania funkcie API. Skontrolujte výsledky týchto volaní, aby ste sa uistili, že je všetko v poriadku a funkcia sa úspešne ukončila;
• použite ladiaci program systému Windows, ako je CodeView, a ladiacu verziu systému Windows (poskytnutá v súprave Windows SDK). Tieto nástroje dokážu odhaliť chybu parametra a aspoň určiť, ktorá funkcia API chybu spôsobuje;
• použiť ďalšie nástroje tretích strán na kontrolu typov parametrov a platnosti ich hodnôt. Takéto nástroje dokážu nielen nájsť chyby parametrov, ale dokonca ukázať na riadok kódu VB, kde sa chyba vyskytla.

Okrem toho je potrebné skontrolovať výsledok vykonania funkcie API.

8. Pamätajte, že celé čísla vo VB a vo Windows nie sú to isté. V prvom rade by ste mali mať na pamäti, že výraz "Integer" vo VB označuje 16-bitové číslo, v dokumentácii Win 32 - 32-bitové číslo. Po druhé, celé čísla (Integer a Long) vo VB sú hodnoty so znamienkom (to znamená, že jeden bit sa používa ako znamienko, zvyšok sa používa ako mantisa čísla), v systéme Windows sa používajú iba nezáporné čísla. Túto okolnosť je potrebné mať na pamäti, keď vytvárate odovzdávaný parameter pomocou aritmetických operácií (napríklad vypočítajte adresu sčítaním základu a posunu). Štandardné aritmetické funkcie VB nie sú na to vhodné. Ako byť v tomto prípade, budeme hovoriť samostatne.

9. Venujte veľkú pozornosť názvom funkcií. Na rozdiel od Win16 sú názvy všetkých funkcií Win32 API citlivé na presné použitie malých a veľkých písmen (vo Win16 to tak nebolo). Ak niekde použijete malé písmeno namiesto veľkého alebo naopak, požadovaná funkcia sa nenájde. Dávajte si tiež pozor na správne používanie prípony A alebo W vo funkciách, ktoré preberajú parametre reťazca. (Viac o tom nájdete nižšie.)

10. Často si ukladajte prácu. Chyby súvisiace s nesprávnym používaním DLL a Win API môžu viesť k zlyhaniu prostredia VB a možno aj celého operačného systému. Mali by ste sa uistiť, že kód, ktorý napíšete pred spustením testu, sa uloží. Najjednoduchšie je nastaviť moduly projektu na automatické nahrávanie pred spustením projektu vo VB.

Po prečítaní predchádzajúceho tipu si možno pomyslíte, že používanie funkcií Win API je riskantná záležitosť. Do istej miery je to pravda, ale len v porovnaní s bezpečným programovaním, ktoré poskytuje samotná VB. No pri ich šikovnej aplikácii a znalosti možných nástrah je toto riziko minimálne. Okrem toho je často jednoducho nemožné úplne opustiť používanie Win API - budú stále potrebné pre akýkoľvek seriózny vývoj.

Okrem toho sme už skôr spomenuli „úskalia“ pre širokú triedu DLL. V prípade Win API je všetko oveľa jednoduchšie, keďže forma volania týchto funkcií je tu jednoznačne zjednotená. Pritom je potrebné mať na pamäti nasledujúce kľúčové body:

1. Funkcie Win32 API sú presne funkcie, teda procedúry typu Function (v Win16 API bolo veľa Sub rutín). Toto sú všetky funkcie typu Long, takže ich popisy sú napísané takto: Declare Function name ... As Long ‘ je explicitne definovaný typ funkcie _

   Deklarovať názov funkcie a typ funkcie _ je definovaný s príponou

   Volanie funkcie API vyzerá takto:

Vysledok& = ApiName& ([ ArgumentList]

1. Návratovou hodnotou funkcie je najčastejšie kód ukončenia operácie. Navyše nenulová hodnota v tomto prípade znamená normálne dokončenie, nula - chyba. Zvyčajne (ale nie vždy) môžete skontrolovať povahu chyby volaním funkcie GetLastError. Popis tejto funkcie je nasledovný: Declare Function GetLastError& Lib "kernel32" ()

   POZOR! Pri práci vo VB je najlepšie použiť vlastnosť LastDLLError objektu Err na získanie hodnoty spresneného chybového kódu, pretože VB niekedy resetuje funkciu GetLastError medzi volaním API a pokračovaním vo vykonávaní programu.

   Kód, ktorý vracia GelLastError, môžete interpretovať pomocou konštánt napísaných v súbore API32.TXT s názvami začínajúcimi príponou ERROR_.

   Väčšina typické chyby majú nasledujúce kódy:

   • ERROR_INVALID_HANDLE = 6& - neplatný popisovač
   • ERROR_CALL_NOT_IMPLEMENTED = 120& - volanie vo Windows 9x funkcia dostupná len pre Windows NT
   • ERROR_INVALID_PARAMETER = 87& - neplatná hodnota parametra

   Mnoho funkcií však vracia hodnotu niektorého požadovaného parametra (napríklad OpenFile vracia hodnotu deskriptora súboru). V takýchto prípadoch je chyba definovaná nejakou inou špeciálnou hodnotou Return&, najčastejšie 0 alebo -1.

2. Rozhrania API Win32 používajú prísne fixné spôsoby odovzdávania najjednoduchších typov údajov. a) ByVal ... Tak dlho

   Dlhé premenné spracovávajú aspoň 80 % odovzdania argumentov. Všimnite si, že argument vždy nasleduje kľúčové slovo ByVal, čo okrem iného znamená, že sa vykonáva jednosmerný prenos dát - z programu VB do funkcie API.

   B) ByVal ... Ako reťazec

   Tento typ prenosu dát je tiež celkom bežný a s argumentom tiež vždy Používa sa ByVal. Pri volaní funkcie API sa adresa reťazca zapíše do zásobníka, takže v tomto prípade je možná obojsmerná výmena údajov. Pri práci so strunami je potrebné si uvedomiť niekoľko nebezpečenstiev.

   Prvým je, že pamäť je vo volajúcom programe vyhradená pre reťazec, takže ak bude funkcia API vypĺňať reťazce, potom pred jej volaním musíte vytvoriť reťazec požadovanej veľkosti. Napríklad funkcia GetWindowsDirectory vráti cestu k adresáru Windows, ktorý podľa definície nesmie byť dlhší ako 144 znakov. Volanie tejto funkcie by teda malo vyzerať asi takto:

   WinPath$ = Space$(144) ‘rezervný reťazec v _ 144 znakoch Result& = GetWindowsDirectory& (WinTath$, 144) _ ‘buffer fill’ Result& - skutočný počet znakov v názve adresára _ WinPath$ = Left$(WinPath, Result&)

   Druhým problémom je, že pri volaní funkcie API sa zdrojový reťazec skonvertuje na nejakú jeho internú reprezentáciu a naopak, keď sa funkcia ukončí. Ak v dobe Win16 táto operácia spočívala len v pridaní nulového bajtu na koniec reťazca, tak s príchodom Win32 sa k tomu pridala aj transformácia dvojbajtového kódovania Unicode na ANSI a naopak. (Toto bolo podrobne rozobraté v článku "Funkcie práce s reťazcovými premennými vo VB", ComputerPress 10'99 a 01'2000). Zatiaľ si všimnite, že pomocou konštrukcie ByVal ... As String môžete vymieňať reťazce iba so znakovými údajmi.

   C) ... Ako každý

   To znamená, že do zásobníka sa vloží nejaká adresa vyrovnávacej pamäte, ktorej obsah bude interpretovať napríklad funkcia API v závislosti od hodnoty iných argumentov. Avšak As Any možno použiť iba v príkaze Declare – špecifická premenná musí byť definovaná ako argument, keď sa uskutoční špecifické volanie funkcie.

   D) ... Ako UserDefinedType

   Takáto konštrukcia sa často používa aj vtedy, keď je potrebné vymieňať dáta (spravidla v oboch smeroch) pomocou nejakej štruktúry. Tento konštrukt je vlastne nejakým druhom konkrétnej implementácie formulára As Any transfer, len je v tomto prípade funkcia nastavená na pevnú štruktúru.

   Forma dátovej štruktúry je definovaná konkrétnou funkciou API a je na zodpovednosti programátora, aby ju správne popísal a rezervoval vo volajúcom programe. Taký dizajn vždy použité bez slová ByVal, čiže v tomto prípade sa vykoná odovzdanie odkazom - adresa premennej sa zapíše do zásobníka.

Príklad volania funkcie API

Vyššie uvedené ilustrujme na príklade použitia dvoch užitočných súborových funkcií – lopen a lread , ktoré sú opísané nasledovne:

Deklarovať funkciu lread Lib „kernel32“ _ Alias ​​​​„_lread“ (_ ByVal lpFileName ako reťazec, _ ByVal wReadWrite ako dlhý) Ako dlho deklarovať funkciu lread Lib „kernel32“ _ Alias ​​​​„_lread“ (_ ByVal hFile As Long, lpBuffer As Any, _ ByVal wBytes As Long) As Long

Vo VB sú ich protipólmi – v tomto prípade presnými – operátory Open a Get (pre binárny režim). Okamžite venujme pozornosť použitiu kľúčového slova Alias ​​v deklarácii funkcie - to je len prípad, keď sa bez neho nezaobídete. Názvy skutočných funkcií v knižnici začínajú podčiarkovníkom (typický štýl C), čo nie je povolené vo VB.

Operácia otvorenia súboru môže vyzerať takto:

Const INVALID_HANDLE_VALUE = -1 ' neplatná _ hodnota manipulátora lpFileName$ = “D:\calc.bas” ' názov súboru wReadWrite& = 2 ' režim čítania a zápisu hFile& = lopen(lpFileName$, wReadWrite&) _ ' = definovať popisovač súboru Ak hFile_LEVALUE Potom _ ' chyba pri otváraní súboru ' Určenie kódu chyby CodeError& = Err.LastDllError 'CodeError& = GetLastError _ ' táto konštrukcia nefunguje End If

Tu musíte venovať pozornosť dvom bodom:

• ako hodnotu funkcie dostaneme hodnotu deskriptora súboru. Chyba zodpovedá hodnote -1;
• práve v tomto prípade nefunguje volanie funkcie GetLastError - aby sme získali spresnenú chybovú hodnotu, obrátili sme sa na objekt Err (o možnosti takejto situácie sme hovorili vyššie).

Potom si môžete prečítať obsah súboru, ale to predpokladá, že programátor musí trochu rozumieť jeho štruktúre (rovnako ako sa to stáva pri práci s ľubovoľnými binárnymi súbormi). V tomto prípade môže volanie funkcie lread vyzerať takto:

Dim MyVar As Single wBytes = lread (hFile&, MyVar, Len(MyVar) ‘ read Reálne číslo, 4 bajty ' wBytes - počet skutočne načítaných údajov, ' -1 - chyba... Typ MyStruct x As Single i As Integer End Type Dim MyVar As MyStruct wBytes = lread (hFile&, MyVar, Len(MyVar)) ' čítanie údajov štruktúra, 6 bajtov

Opäť si všimnite, že druhý argument funkcie sa odovzdáva odkazom, zvyšok hodnotou.

Dim MyVar As String MyVar = Space$(10) 'rezervná premenná pre 10 znakov wBytes = lread (hFile&, ByVal MyVar, Len(MyVar)) ' čítanie reťazca znakov, 10 znakov

Tu môžete vidieť dôležitý rozdiel oproti predchádzajúcemu príkladu – reťazcová premenná je nevyhnutne sprevádzaná kľúčovým slovom ByVal.

Čítanie obsahu súboru v poli (pre jednoduchosť použijeme jednorozmerné bajtové pole) sa vykonáva takto:

Dim MyArray(1 až 10) As Byte wBytes = lread (hFile&, MyArray(1), _ Len(MyArray(1))* 10) ‘ čítanie 10 prvkov poľa

Zadaním prvého prvku poľa ako argumentu odovzdávame adresu začiatku oblasti pamäte vyhradenej pre pole. Je zrejmé, že akýkoľvek fragment poľa možno vyplniť týmto spôsobom:

WBytes = lread (hFile&, MyArray(4), _ Len(MyArray(1))* 5) ' čítanie prvkov poľa od 4. do 8.

Tip 5: Použite alias na prenosy a parametre Ako každý

Tu na základe predchádzajúceho príkladu odhalíme podstatu štvrtého tipu Dana Applemana.

Pri práci s funkciou lread by ste mali pamätať na to, že pri prístupe pomocou reťazcovej premennej musíte použiť kľúčové slovo ByVal (inak sa nedá vyhnúť správe o nelegálnej operácii). Ak chcete byť v bezpečí, môžete urobiť ďalší špeciálny popis tej istej funkcie, aby fungovala iba s premennými reťazca:

Deklarovať funkciu lreadString Lib "kernel32" _ Alias ​​"_lread" (_ ByVal hFile As Long, ByVal lpBuffer As Long, _ ByVal wBytes As Long) As Long

Pri práci s týmto popisom už nemusíte pri prístupe špecifikovať ByVal:

WBytes = lreadString (hFile&, MyVarString, _ Len(MyVarString)) '

Zdá sa, že syntax operátora Declare vám umožňuje urobiť takéto špeciálne vyhlásenie pre pole:

Deklarovať funkciu lreadString Lib „kernel32“ Alias ​​​​„_lread“ (_ ByVal hFile As Long, lpBuffer() As Byte, _ ByVal wBytes As Long) As Long

Avšak odvolanie

WBytes = lreadArray(hFile&, MyArray(), 10)

nevyhnutne vedie k fatálnej chybe programu.

Toto je pokračovanie rozhovoru o zvláštnostiach spracovania reťazcových premenných vo Visual Basic: VB používa dvojbajtové kódovanie Unicode, Win API používa jednobajtové kódovanie ANSI (navyše s formátom prijatým v C, s nulovým bajtom nakoniec). Preto pri použití reťazcových premenných ako argumentu sa konverzia z Unicode na ANSI vždy automaticky vykoná pri volaní funkcie API (presnejšie funkcie DLL) a spätná konverzia pri návrate.

Vyvodenie z toho je jednoduché: Reťazcové premenné možno použiť na výmenu znakových údajov, ale nemožno ich použiť na výmenu ľubovoľných binárnych informácií (ako to bolo v prípade 16-bitových verzií VB). V druhom prípade je lepšie použiť jednorozmerné bajtové pole.

Ako viete, typ String možno použiť na popis vlastnej štruktúry. V tejto súvislosti je potrebné pamätať na nasledovné:

• Na prístup k Win API je prísne zakázané používať nasledujúcu konštrukciu: Type MyStruct x As Single s As String ‘ reťazec s premenlivou dĺžkou End Type

  V prípade reťazca s premenlivou dĺžkou je reťazcový deskriptor odovzdaný ako súčasť štruktúry so všetkými z toho vyplývajúcimi dôsledkami vo forme chyby vykonávania programu.

• Ako prvok štruktúry môžete použiť reťazec s pevnou dĺžkou: Typ MyStruct x As Single s As String*8 ‘ reťazec s pevnou dĺžkou End Type

V tomto prípade sa vykoná zodpovedajúca konverzia kódovania.

A posledná poznámka: pri prístupe k funkcii API v žiadnom prípade nemôžete použiť pole reťazcových premenných (pevnej aj premennej dĺžky). V opačnom prípade bude zaručený vznik „nezákonnej operácie“.

Je pravdepodobné, že budete mať situáciu, keď budete musieť napísať svoje vlastné funkcie DLL. Potreba toho nevyhnutne vznikne, ak použijete technológiu zmiešaného programovania - použitie dvoch alebo viacerých programovacích jazykov na implementáciu jednej aplikácie.

V tejto súvislosti poznamenávame, že zmiešané programovanie je celkom bežné pre implementáciu pomerne zložitej aplikácie. Každý jazyk (presnejšie programovací systém založený na jazyku) má totiž svoje silné a slabé stránky, preto je celkom logické využívať výhody rôznych nástrojov na riešenie rôznych problémov. Napríklad VB - na vytvorenie používateľského rozhrania, C - na efektívny prístup k systémovým zdrojom, Fortran - na implementáciu numerických algoritmov.

Názor autora je nasledovný: každé seriózne programovanie vyžaduje, aby vývojár vlastnil aspoň dva nástroje. Samozrejme, v dnešných podmienkach jasnej deľby práce je veľmi ťažké byť vynikajúcim odborníkom aj v dvoch systémoch, takže schéma „hlavný a pomocný jazyk“ je logickejšia. Ide o to, že aj malá znalosť „pomocného“ jazyka (písanie pomerne jednoduchých postupov) môže výrazne zlepšiť efektivitu „hlavného“ jazyka. Všimnite si, že znalosť VB, aspoň ako pomocná, je dnes takmer povinnou požiadavkou profesionálneho programátora. Mimochodom, v časoch DOSu pre každého programátora, vrátane Basicu, bolo veľmi žiaduce poznať základy Assemblera.

Tak či onak, ale aj v podmienkach skupinovej práce, keď sa každý programátor zaoberá vlastným špecifickým podnikaním, by všetci účastníci projektu mali mať predstavu o vlastnostiach procedurálneho rozhrania v rôznych jazykoch. A vedieť, že mnohé programovacie systémy (vrátane VB) umožňujú okrem predvoleného rozhrania použiť aj iné, rozšírené metódy volania procedúr, ktoré umožňujú prispôsobiť rozhranie inému jazyku.

Pri štúdiu interprocedurálneho rozhrania by ste mali venovať pozornosť nasledujúcim možným „úskaliam“:

• Rôzne jazyky môžu používať rôzne konvencie na písanie identifikátorov. Napríklad je bežné používať podčiarkovník na začiatku názvu procedúry, čo nie je povolené vo VB. Tento problém sa dá ľahko vyriešiť použitím kľúčového slova Alias ​​v príkaze Declare (pozri napríklad Tip 2-3).
• Je možné použiť inú postupnosť zápisu odovzdaných argumentov do zásobníka. Napríklad v časoch DOSu (aby som bol úprimný - neviem, ako to teraz vyzerá v prostredí Windows), C písalo argumenty z konca zoznamu, iné jazyky​​(Fortran, Pascal, Basic ) - od začiatku.
• Štandardne sa používajú rozdielne princípy odovzdávanie parametrov - odkazom alebo hodnotou.
• Rôzne princípy ukladania reťazcových premenných. Napríklad v C (rovnako ako vo Fortrane a Pascale) je dĺžka reťazca určená nulovým bajtom na jeho konci, zatiaľ čo v Basic je dĺžka zapísaná explicitne v deskriptore reťazca. Samozrejme, treba pamätať na možnosť použitia rôznych kódovaní znakov.
• Pri prenose viacrozmerných polí je potrebné pamätať na to, že existujú rôzne možnosti prevodu viacrozmerných štruktúr na jednorozmerné (počnúc od prvého indexu alebo od posledného vo vzťahu k dvojrozmerným poliam - „po riadkoch“ alebo „po stĺpcoch). “).

S ohľadom na to je možné sformulovať nasledujúce odporúčania:

• Použite najjednoduchšie, osvedčené spôsoby odovzdávania argumentov funkciám DLL. Štandardy prijaté pre Win API sú celkom vhodné ako model.
• Nikdy neodovzdávajte polia reťazcových premenných.
• Buďte veľmi opatrní pri odovzdávaní jednoduchých reťazcových premenných a viacrozmerných polí.
• Nezabudnite špeciálnym spôsobom skontrolovať funkčnosť mechanizmu odovzdávania argumentov do a z volanej procedúry. Napíšte vlastný test na kontrolu prenosu údajov. Samostatne skontrolujte, či je každý argument odovzdaný správne. Napríklad, ak máte postup s niekoľkými argumentmi, najprv skontrolujte správnosť odovzdania každého parametra pre variant s jedným argumentom a až potom - pre celý zoznam.

Ale čo ak je funkcia DLL už napísaná napríklad vo Fortrane, ale jej vstupné rozhranie príliš nezapadá do vyššie uvedených štandardov VB? Tu sú dve rady. Po prvé: napíšte testovaciu funkciu DLL a použite ju na pokus o nájdenie správneho volania z programu VB metódou pokus-omyl. Po druhé: v rovnakom Fortrane napíšte procedúru adaptéra, ktorá by poskytla jednoduché rozhranie medzi VB a funkciou DLL s transformáciou jednoduchých dátových štruktúr na zložité (napríklad konverzia viacrozmerného poľa bajtov na pole reťazcov).

Takže: použite funkcie DLL. Ale buďte ostražití...

ComputerPress 9 "2000

Rozhrania API môžu byť zábavné aj frustrujúce zároveň. Na jednej strane interakciou s inými aplikáciami môžete výrazne zvýšiť dosah publika a „wow efekt“ vašej aplikácie. Na druhej strane to zahŕňa čítanie ton dokumentácie, učenie sa o stratégiách autentifikácie a analýzu neinformatívnych (alebo dokonca chýbajúcich) chybových správ.

Po prvé, ak stále úplne nerozumiete tomu, čo je API (Application Programming Interface), prečítajte si vysvetlenie Skillcrush a potom prvú časť tohto článku, aby ste to dohnali.

„API“ je neuveriteľne široký pojem – zakaždým, keď vaša aplikácia „komunikuje“ s inou aplikáciou, je to prostredníctvom nejakého druhu API. Komponenty vo vašej vlastnej aplikácii, podobne ako rôzne časti Rails, spolu tiež komunikujú prostredníctvom API. Sú to viac-menej nezávislé podaplikácie, ktoré prenášajú údaje, ktoré každá potrebuje na vykonávanie svojich vlastných špecifických úloh. Vo svete aplikácií je všetko API!

Keď vytvoríte aplikácie s dynamickejšími front-endovými funkciami (ako jednostránkové Javascriptové aplikácie, tak aj jednoduché aplikácie so samostatnými volaniami AJAX), budú komunikovať s backendom Rails cez vaše vlastné API, čo je v skutočnosti len jeden alebo tri riadky kódu navyše. ., ktoré svojim kontrolérom povie, ako majú poskytovať JSON alebo XML namiesto HTML.

V tomto návode sa naučíte, ako vytvoriť vlastné API. V nasledujúcich lekciách sa budeme zaoberať tým, ako interagovať s rozhraniami API iných aplikácií. Lekcie by mali byť dobrým odrazovým mostíkom pre učenie sa o tejto téme, ale je nepravdepodobné, že budú schopné úplne pokryť všetky prípady. Veľká časť práce s API je schopnosť čítať ich dokumentáciu a zistiť, čo od vás chcú.

Body na zamyslenie

Skontrolujte otázky a zistite, či poznáte odpovede. Po dokončení úlohy sa znova skontrolujte.

• Ako Rails chápe, aký typ súboru očakávate ako odpoveď, keď odošlete požiadavku HTTP.
• Aký je účel metódy #respond_to?
• Ako vrátite objekt používateľa (User) pri špecifikovaní atribútov, ktoré nechcete zahrnúť do tohto objektu (t. j. nemôžete len vrátiť User.first)?
• Pomenujte 2 kroky zo zákulisia metódy #to_json.
• Ako poviem akcii ovládača, aby zobrazila iba chybové hlásenie?
• Ako vytvoriť vlastnú chybovú správu?
• Prečo nemôžete použiť metódy overovania radiča založené na reláciách, ak chcete povoliť programové pripojenie k vášmu API?
• Čo je to „architektúra orientovaná na služby“?

Základy API

Vaša aplikácia Rails je v skutočnosti už API, aj keď si to možno nemyslíte ako API. Webový prehliadač, ktorý spustia vaši používatelia, je tiež program, takže v skutočnosti odošle požiadavku API do vašej aplikácie Rails, keď používateľ otvorí novú stránku. Máme tendenciu uvažovať týmto spôsobom, pretože vykresľovanie HTML šablón je taká bežná úloha, že túto funkcionalitu jednoducho zakódujeme do našich serverových programov ako štandardný typ odpovede a všetko ostatné považujeme za niečo neobvyklé.

Často však chcete podať žiadosť, ktorá nevyžaduje, aby ste museli prejsť všetkými bolesťami hlavy pri používaní prehliadača. Možno vás nezaujíma štruktúra stránky (HTML), ale na oplátku chcete čisté dáta. Povedzme, že chcete získať zoznam všetkých používateľov. Môžete požiadať o niečo ako http://yourapplication.com/users , čo pravdepodobne spustí akciu #index a vykreslí zoznam všetkých používateľov aplikácie.

Ale prečo sa obťažovať všetkými týmito dodatočnými informáciami, keď všetko, čo chcete, je zoznam používateľov? Najjednoduchšou možnosťou by bolo odoslať požiadavku na rovnakú adresu URL s uvedením očakávanej odpovede JSON alebo XML. Ak správne nastavíte ovládač Rails, získate späť jednoduchý objekt poľa JSON obsahujúci všetkých používateľov. úžasné!

Rovnaký princíp platí, keď komunikujete s externým API. Povedzme, že chcete získať najnovšie „tweety“ používateľa zo služby Twitter. Všetko, čo musíte urobiť, je povedať svojej aplikácii Rails, ako má interagovať s rozhraním Twitter API (t. j. overiť sa), odoslať žiadosť a spracovať súbor „tweetov“, ktoré sa vrátia.

Vytvorenie API

Možno budete chcieť zo svojej aplikácie Rails vytvoriť čisté rozhranie API pre klientske webové stránky, alebo sa jednoducho budete chcieť naučiť, ako odosielať JSON, keď to front-end požaduje. Táto časť sa nebude zaoberať tým, ako vytvoriť plnohodnotné RESTful API s funkciou autentifikácie. Toto je hladký úvod do zaobchádzania s vašou aplikáciou ako s API.

Základy

Ak chcete, aby vaša aplikácia Rails vracala JSON namiesto HTML, musíte to povedať svojmu ovládaču. Skvelé je, že rovnaká akcia ovládača sa môže vrátiť odlišné typy v závislosti od toho, či váš používateľ zadáva bežnú požiadavku prehliadača alebo pristupuje k API cez príkazový riadok. Toto určuje, aký typ požiadavky bol uskutočnený na základe prípony požadovaného súboru, ako napríklad example.xml alebo example.json .

Môžete skontrolovať, čo si Rails "myslí" o type súboru, ktorý očakávate, skontrolovaním denníka servera:

Spustenie GET "/posts/new" pre 127.0.0.1 dňa 2013-12-02 15:21:08 -0800 Spracovanie PostsController#new as HTML

Prvý riadok vám povie, aká adresa URL bola požadovaná, a druhý vám povie, kam bola nasmerovaná a ako s ňou Rails narába. Ak by ste použili rozšírenie .json, vyzeralo by to takto:

Spustenie GET "/posts.json" pre 127.0.0.1 dňa 2013-12-04 12:02:01 -0800 Spracovanie PostsController#index ako JSON

Ak máte spustenú testovaciu aplikáciu, skúste požiadať o iné adresy URL. Ak váš ovládač nevie, ako s nimi zaobchádzať, môže sa vám zobraziť chyba, ale stále by ste mali byť schopní vidieť, čo Rails rozumie vašim požiadavkám.

Vykresľovanie JSON alebo XML

Keď sa rozhodnete, že chcete odpovedať pomocou JSON alebo XML, budete musieť povedať svojmu kontrolórovi, aby namiesto HTML vykreslil JSON alebo XML. Jedným zo spôsobov, ako to urobiť, je použiť metódu #respond_to:

Trieda UsersController< ApplicationController def index @users = User.all respond_to do |format| format.html # index.html.erb format.xml { render xml: @users } format.json { render json: @users } end end end

V tomto prípade #respond_to odovzdá do bloku objekt formátu, ku ktorému môžete pripojiť príslušné volanie vykresľovania. Ak neurobíte nič, html sa vykreslí pomocou štandardnej šablóny Rails (v tomto príklade app/views/index.html.erb).

Funkcia #render je dostatočne inteligentná na to, aby pochopila, ako vykresliť širokú škálu formátov. Keď mu odovzdáte key:json , zavolá #to_json na hodnote in tento príklad pre @používateľov . Týmto sa vaše objekty Ruby skonvertujú na reťazce JSON, ktoré budú odovzdané žiadajúcej aplikácii.

Takto získate svoje API. Samozrejme, vytvorenie API môže byť trochu komplikovanejšie, ak chcete robiť nejaké fantastické veci, ale je to všetko o základoch.

Zadanie atribútov vrátenia

Povedzme, že sa chcete uistiť, že nevraciate e-mailovú adresu používateľa spolu s objektom používateľa. V tomto prípade budete chcieť zmeniť atribúty, ktoré budú vrátené, a upraviť to, čo robí metóda #to_json.

Predtým by ste jednoducho prepísali metódu #to_json svojou verziou, ale teraz to už nemusíte – v skutočnosti namiesto toho prepíšete metódu #as_json. Metóda #as_json sa používa v metóde #to_json, takže jej úpravou sa implicitne zmení výsledok #to_json , ale dosť špecifickým spôsobom.

#to_json robí 2 veci: spustí #as_json a získa hash atribútov, ktoré sa majú vykresliť do JSON. Potom sa vykreslí do JSON pomocou ActiveSupport::json.encode . Takže úpravou #as_json ste konkrétnejší v časti metódy #to_json, ktorú skutočne chcete zmeniť.

V našom prípade to robíme úpravou #as_json v našom modeli tak, aby vrátil iba atribúty, ktoré potrebujeme:

# app/models/user.rb class User< ActiveRecord::Base # Вариант 1: Полное переопределение метода #as_json def as_json(options={}) { :name =>self.name ) # NEZAHRŇUJTE koncové pole e-mailu # Možnosť 2: Použiť štandardná metóda#as_json def as_json(options=()) super(iba: [:name]) end end

Potom v našom ovládači všetko, čo musíme urobiť, je vykresliť JSON ako normálne (príklad nižšie vždy vráti JSON, či už bola odoslaná požiadavka HTML alebo nie):

# app/controllers/users_controller.rb trieda UsersController< ApplicationController def index render json: User.all end end

Všimnite si, že pri použití #render nemusíte sami volať #to_json – urobí to za vás.

Heroku môže niekedy vyžadovať ďalšie kroky na správne zobrazenie vašich chybových stránok. Pozri. Možno budete musieť najprv odstrániť statické stránky z adresára app/public.

Zabezpečenie zvonku

Povedzme, že chcete povoliť prístup k API iba vtedy, ak je používateľ prihlásený. Vaša existujúca autentifikácia ovládača už funguje – len sa uistite, že máte nastavenú správnu #before_action (napr. before_action:require_login). Možno budete chcieť funkcionalitu, pri ktorej si stránku môžu prezerať prihlásení aj neprihlásení používatelia, ale každý potrebuje vidieť iné údaje. Nechcete, aby neprihlásení používatelia mohli zadávať požiadavky API na získanie citlivých údajov. Podobne nechcete povoliť neautorizovaným používateľom návštevu určitých stránok HTML.

Ak chcete spracovať požiadavky z aplikácie, ktorá nie je prehliadačom (napr príkazový riadok), pri autentifikácii sa nemôžete spoliehať na súbory cookie prehliadača. To je dôvod, prečo väčšina rozhraní API používa natívne tokeny ako súčasť procesu autentifikácie. O tokenoch si povieme niečo viac v nasledujúcej lekcii.

Ďalšie kroky

Teraz máte schopnosti používať svoju aplikáciu Rails nielen na HTML, ale aj na akýkoľvek iný formát. Ak chcete ísť ďalej a nechať iných vývojárov vytvárať veci pomocou vašej platformy (napríklad, aby mohli namiesto overovania ako používateľ vytvárať programové požiadavky), budete musieť svoj systém API oveľa bezpečnejšie zabezpečiť. Nebudeme sa tu zaoberať všetkým, ale pozrite sa na nasledujúce:

• Článok Building Awesome Rails APIs popisuje mnohé z najlepších prístupov na prechod z hračkárskej aplikácie na priemyselné štandardné rozhrania API.

Architektúra orientovaná na služby

Je čas predstaviť architektonický prístup s názvom Service-Oriented Architecture (SOA). Základnou myšlienkou je, že vaša aplikácia bude pozostávať z mnohých služieb, ako je platobný systém, registrácia používateľov, modul odporúčaní atď. Namiesto toho, aby ste to všetko budovali v rámci jednej hlavnej aplikácie, rozdeľujete podsystémy na úplne nezávislé časti, ktoré medzi sebou interagujú pomocou interných rozhraní API.

To je dobré z mnohých dôvodov. Zabezpečením toho, že každej časti vašej aplikácie nezáleží na tom, ako fungujú ostatné časti, a že bude vedieť, ako požiadať o údaje iba prostredníctvom svojho API, môžete vykonať významné zmeny v kóde služby a zvyšok aplikácie bude fungovať ako predtým. Jednu službu môžete úplne nahradiť inou a pokiaľ komunikuje pomocou rovnakých metód API, pôjde to veľmi hladko. Môžete použiť externé rozhrania API ako súčasť svojej aplikácie (napríklad spracovateľov platieb) namiesto písania vlastných. Môžete vytvoriť aplikáciu PHP, ktorá spolupracuje s aplikáciou Python, ktorá spolupracuje s aplikáciou Rails, a všetko bude fungovať, pretože medzi sebou komunikujú pomocou API.

Vo všeobecnosti je dobré snažiť sa, aby každá časť vašej aplikácie bola čo najviac nezávislá. Koncept SOA vás povzbudzuje, aby ste premýšľali presne o tom, aké metódy chcete vystaviť iným častiam vašej aplikácie, a vďaka tomu bude váš kód lepší. Navyše, za predpokladu, že každý hlavný komponent vašej aplikácie je nezávislý, môžete tiež oveľa jednoduchšie izolovať problémy a inteligentnejšie riešiť chyby.

Použitie architektúry orientovanej na služby pre celú aplikáciu je ako rozloženie obrovského, zložitého skriptu Ruby na šikovné triedy a metódy, len vo väčšom meradle.

Jedným z najznámejších prípadov prechodu na architektúru orientovanú na služby je Amazon.com. Jedného dňa v roku 2002 Jeff Bezos otvorene vyhlásil, že všetky pracovné tímy musia prejsť na SOA, inak budú prepustené. Notoricky známy príspevok v blogu zamestnanec spoločnosti Google, určený na interné účely, ale náhodne vystavený verejnosti, hovoril o sile Amazonu pomocou SOA. Toto je skvelé čítanie, takže ho určite ohodnoťte, ale hlavné tézy Bezosovho listu sú vyňaté z nasledujúcich citátov z príspevku:

1) Všetky príkazy teraz poskytujú svoje údaje a funkcie prostredníctvom servisných rozhraní.

2) Tímy musia medzi sebou komunikovať prostredníctvom týchto rozhraní.

3) Iné formy medziprocesovej komunikácie sú zakázané: žiadne priame prepojenia, žiadne priame čítanie údajov z iného príkazu, žiadne modely zdieľanej pamäte, žiadne „zadné vrátka“ a podobne. Jediným povoleným spôsobom komunikácie je prístup k rozhraniu služby cez sieť.

4) Nezáleží na tom, akú technológiu používajú. HTTP, Corba, Pubsub, natívne protokoly – na tom nezáleží. Bezosovi je to jedno.

5) Všetky servisné rozhrania bez výnimky musia byť pôvodne navrhnuté tak, aby bolo možné ich ovládať zvonku. To znamená, že tím musí plánovať a navrhovať, aby bol schopný poskytnúť rozhranie pre vývojárov mimo spoločnosti. Bez výnimky.

6) Každý, kto ignoruje tieto požiadavky, bude prepustený.

SOA je vážna vec. Iste, existuje veľa problémov, ktoré sa vyskytnú pri jeho používaní - pozrite si tento príspevok o "poučeniach" Amazonu - ale má neuveriteľné množstvo výhod.

Počas vytvárania „hračkových“ aplikácií si so SOA pravdepodobne nebudete príliš lámať hlavu, no táto otázka vás určite napadne, keď začnete pracovať pre IT spoločnosť, takže oboznámenie sa s ňou je dobrou praxou.

Tvoj cieľ

1. Prečítajte si časť 7 príručky Rails Guide to Controllers, kde sa dozviete o vykresľovaní JSON a XML.
2. Nevyžaduje sa ich prezeranie (pretože idú o niečo ďalej, ako sme momentálne pripravení), ale ak máte záujem, pozrite sa na Railscasts v sekcii Ďalšie zdroje v spodnej časti návodu, kde sa dozviete viac o výhody API.

Záver

Počas kurzu Javascript budeme užšie spolupracovať s vašou aplikáciou ako API. V tomto kurze vytvoríte niekoľko úplných aplikácií, ktoré používajú volania AJAX pre lepšiu používateľskú skúsenosť, čo v skutočnosti zahŕňa vykresľovanie údajov XML alebo JSON namiesto úplnej stránky HTML. Potom vytvoríte niekoľko jednostránkových aplikácií Javascript, ktoré sa spoliehajú na API poskytované vašou aplikáciou Rails, aby získali všetky potrebné údaje z databázy a inak sa spúšťajú na strane klienta (v prehliadači).

Najlepší spôsob, ako sa vysporiadať s API, je vytvoriť ho a interagovať s ním, na čo sa zameriame v našich projektoch.