Comment travailler avec l'API d'une application tierce. Classification des huiles moteur selon API. Plans de développement d'API

Ce court terme est bien connu de tous ceux qui ont rencontré d'une manière ou d'une autre le développement. Mais tout le monde ne comprend pas exactement ce que cela signifie et pourquoi c'est nécessaire. Développeur Piotr Gazarov a parlé de l'API en termes simples dans son blog.

L'abréviation API signifie "Application Programming Interface" (interface de programmation d'application, interface de programmation d'application). La plupart des grandes entreprises développent à un certain stade des API pour des clients ou pour usage domestique. Pour comprendre comment et comment l'API est utilisée dans le développement et les affaires, vous devez d'abord comprendre comment fonctionne le World Wide Web.

World Wide Web et serveurs distants

Le WWW peut être considéré comme un immense réseau de serveurs liés qui stockent chaque page. ordinateur portable ordinaire peut être transformé en un serveur capable de servir un site entier sur le réseau, et serveurs locaux les développeurs utilisent pour créer des sites avant de les ouvrir à un large éventail d'utilisateurs.

Lors de la saisie dans la barre d'adresse d'un navigateur www.facebook.com une requête correspondante est envoyée au serveur Facebook distant. Une fois que le navigateur reçoit la réponse, il interprète le code et affiche la page.

Chaque fois qu'un utilisateur visite une page sur le Web, il interagit avec l'API du serveur distant. L'API est la partie du serveur qui reçoit les requêtes et envoie les réponses.

L'API comme moyen de servir les clients

De nombreuses entreprises proposent l'API en tant que produit fini. Par exemple, Weather Underground vend l'accès à son API de données météorologiques.

Scénario d'utilisation : sur le site Web d'une petite entreprise, il existe un formulaire de prise de rendez-vous pour les clients. L'entreprise souhaite y intégrer Google Agenda pour donner aux clients la possibilité de créer automatiquement un événement et de renseigner les détails d'une réunion à venir.

Application API : objectif - le serveur du site doit contacter directement le serveur Google avec une demande de création d'un événement avec les détails spécifiés, recevoir une réponse de Google, la traiter et transmettre les informations appropriées au navigateur, par exemple, un message de confirmation à l'utilisateur .

Alternativement, le navigateur peut faire une demande à l'API du serveur Google, en contournant le serveur de l'entreprise.

Que l'API Google Agenda différent de l'API de tout autre serveur distant sur le réseau ?

Techniquement, la différence réside dans le format de la requête et de la réponse. Pour générer une page Web complète, le navigateur attend une réponse en langage de balisage HTML, tandis que l'API Google Calendar renverra uniquement des données dans un format tel que JSON.

Si une demande à l'API est faite par le serveur du site Web de l'entreprise, alors c'est le client (tout comme le client est le navigateur lorsque l'utilisateur ouvre le site Web).

Grâce à l'API, l'utilisateur a la possibilité d'effectuer une action sans quitter le site Web de l'entreprise.

La plupart des sites Web modernes utilisent au moins quelques API tierces. De nombreuses tâches proposent déjà des solutions prêtes à l'emploi développeurs tiers, que ce soit une bibliothèque ou un service. Il est souvent plus facile et plus fiable de recourir à une solution toute faite.

De nombreux développeurs distribuent l'application sur plusieurs serveurs qui interagissent entre eux à l'aide de l'API. Les serveurs qui exécutent une fonction auxiliaire par rapport au serveur d'application principal sont appelés microservices.

Ainsi, lorsqu'une entreprise propose une API à ses utilisateurs, cela signifie simplement qu'elle a créé une série d'URL spéciales qui ne renvoient que des données en réponse.

Ces demandes peuvent souvent être envoyées via le navigateur. Étant donné que le transfert de données via HTTP se fait sous forme de texte, le navigateur pourra toujours afficher la réponse. Par exemple, via un navigateur, vous pouvez accéder directement à l'API GitHub (https://api.github.com/users/petrgazarov), et sans jeton d'accès, et obtenir la réponse suivante au format JSON :

Le navigateur affiche parfaitement une réponse JSON, qui peut être insérée dans le code. Il suffit d'extraire simplement des données d'un tel texte afin de l'utiliser à votre discrétion.

Quelques autres exemples d'API

Le mot « application » (appliqué, application) peut être utilisé dans différentes significations. Dans le contexte de l'API, cela signifie :

• logiciel avec une fonction spécifique,
• le serveur dans son ensemble, l'application dans son ensemble ou simplement une partie distincte de l'application.

Tout logiciel qui peut être clairement distingué de l'environnement peut remplacer la lettre "A" dans l'abréviation anglaise, et peut également avoir une sorte d'API. Par exemple, lorsqu'un développeur implémente une bibliothèque tierce dans le code, celle-ci fait partie de l'ensemble de l'application. Étant un logiciel indépendant, la bibliothèque aura une sorte d'API qui lui permettra d'interagir avec le reste du code de l'application.

Dans la conception orientée objet, le code est représenté comme une collection d'objets. Il peut y avoir des centaines d'objets de ce type interagissant les uns avec les autres dans une application. Chacun d'eux a sa propre API - un ensemble Publique propriétés et méthodes d'interaction avec d'autres objets dans l'application. Les objets peuvent aussi avoir privé, une logique interne cachée de l'environnement et qui n'est pas une API.

Le système de classification des huiles moteur API () a été créé en 1969. Selon le système API, trois catégories opérationnelles (trois rangées) d'utilisation et de qualité des huiles moteur sont établies :
S (service)- se compose de catégories de qualité d'huiles moteur pour moteurs à essence, classées par ordre chronologique.
C (Commercial)- se compose de catégories de qualité et de destination des huiles pour moteurs diesel, classées par ordre chronologique.
CE (conservation de l'énergie)- huiles économes en énergie. Nouvelle ligne huiles de haute qualité, composées d'huiles à faible viscosité et à écoulement facile qui réduisent la consommation de carburant selon les résultats des tests pour moteurs à essence.

Chaque nouvelle classe se voit attribuer une lettre alphabétique supplémentaire. Les huiles universelles pour moteurs à essence et diesel sont indiquées par deux symboles des catégories correspondantes : le premier symbole est le principal, et le second indique la possibilité d'utiliser cette huile pour un autre type de moteur. Exemple : API SM/CF.

Classes de qualité API pour les moteurs à essence

Classe d'API SN- approuvé le 1er octobre 2010.
La principale différence entre l'API SN et les classifications API précédentes est la limitation de la teneur en phosphore pour la compatibilité avec systèmes modernes neutralisation des gaz d'échappement, ainsi qu'une économie d'énergie complète. Autrement dit, les huiles classées selon API SN correspondront approximativement à ACEA C2, C3, C4, sans correction pour la viscosité à haute température.

API classe SM- Approuvé le 30 novembre 2004.
Huiles moteur pour moteurs à essence modernes (multi-soupapes, turbocompressés). Par rapport à la classe SL, les huiles moteur qui répondent aux exigences de l'API SM doivent avoir des niveaux de protection plus élevés contre l'oxydation et l'usure prématurée des pièces du moteur. De plus, les normes concernant les propriétés de l'huile à basse température ont été relevées. Les huiles moteur de cette classe peuvent être certifiées selon la classe d'efficacité énergétique ILSAC.
Les huiles moteur qui répondent aux exigences de l'API SL, SM peuvent être utilisées dans les cas où la classe SJ ou antérieure est recommandée par le constructeur du véhicule.

Classe API SL- huiles moteur pour moteurs de voitures fabriquées après 2000.
Conformément aux exigences des constructeurs automobiles, les huiles moteur de cette classe sont utilisées dans les moteurs turbocompressés à plusieurs soupapes fonctionnant avec des mélanges de carburant pauvres qui répondent aux exigences environnementales accrues modernes, ainsi qu'aux économies d'énergie. Les huiles qui répondent aux exigences de l'API SL peuvent être utilisées dans les cas où la classe SJ ou antérieure est recommandée par le constructeur automobile.

Classe d'API SJ- huiles moteur pour une utilisation dans les moteurs à essence depuis 1996 de la libération.
Cette classe décrit les huiles moteur utilisées dans les moteurs à essence depuis 1996. Les huiles moteur de cette classe sont conçues pour être utilisées dans les moteurs à essence des voitures et des voitures de sport, des minibus et des camions légers, qui sont entretenus conformément aux exigences des constructeurs automobiles. SJ a les mêmes normes minimales que SH et des exigences supplémentaires pour l'accumulation de carbone et le fonctionnement à basse température. Les huiles moteur répondant aux exigences de l'API SJ peuvent être utilisées lorsque SH ou une version antérieure est recommandée par le constructeur du véhicule.

Classe d'API SH- huiles moteur pour moteurs à essence depuis 1994 de sortie.
La classe a été adoptée en 1992 pour les huiles moteur recommandées depuis 1993. Cette classe se caractérise par des exigences plus élevées que la classe SG, et a été développée en remplacement de cette dernière, pour améliorer les propriétés anti-carbone, antioxydantes, anti-usure des huiles et protection accrue contre la corrosion. Les huiles moteur de cette classe sont destinées à être utilisées dans les moteurs à essence des voitures, minibus et camions légers, conformément aux recommandations de leurs fabricants. Les huiles moteur de cette classe ont été testées conformément aux exigences de la Chemical Manufacturers Association (CMA). Les huiles moteur de ce grade peuvent être utilisées lorsque le grade SG ou antérieur est recommandé par le constructeur du véhicule.

API classe SG- huiles moteur pour moteurs à essence depuis 1989 de sortie.
Conçu pour être utilisé dans les moteurs à essence des voitures particulières, des minibus et des camions légers. Les huiles moteur de cette classe ont des propriétés qui offrent une meilleure protection contre les dépôts de carbone, l'oxydation de l'huile et l'usure du moteur, par rapport aux classes précédentes, et contiennent également des additifs qui protègent contre la rouille et la corrosion des pièces internes du moteur. Les huiles moteur de qualité SG répondent aux exigences API CC en matière d'huile pour moteur diesel et peuvent être utilisées là où les qualités SF, SE, SF/CC ou SE/CC sont recommandées.

API classe SF- huiles moteur pour moteurs à essence depuis 1980 (classe obsolète).
Ces huiles moteur ont été utilisées dans les moteurs à essence fabriqués en 1980-1989, sous réserve des recommandations et instructions du constructeur du moteur. Fournit une meilleure résistance à l'oxydation, une meilleure protection contre l'usure par rapport aux huiles de base SE et une meilleure protection contre les boues, la rouille et la corrosion. Les huiles moteur de la classe SF pourraient être utilisées comme substituts des anciennes classes SE, SD ou SC.

Classe API SE- huiles moteur pour moteurs à essence produits depuis 1972 (classe obsolète). Ces huiles moteur ont été utilisées dans les moteurs à essence des modèles 1972-79, ainsi que certains modèles 1971. Protection supplémentaire par rapport aux huiles moteur SC et SD et peuvent être utilisées comme substituts pour ces catégories.

Classe d'API SD- huiles moteur destinées aux moteurs à essence depuis 1968 (classe obsolète). Les huiles moteur de cette classe ont été utilisées dans les moteurs à essence des voitures et de certains camions fabriqués en 1968-70, ainsi que certains modèles en 1971 et plus tard. Protection améliorée par rapport aux huiles moteur SC, également utilisées uniquement lorsque recommandées par le fabricant du moteur.

Classe API SC- huiles moteur pour moteurs à essence, à partir de 1964 (classe obsolète). Ils étaient généralement utilisés dans les moteurs de voitures et de certains camions fabriqués en 1964-1967. Réduit les dépôts à haute et basse température, l'usure et protège contre la corrosion.

API classe SB- huiles moteur pour moteurs à essence de faible puissance (classe obsolète). Huiles moteur des années 30 du 20e siècle, qui offraient une protection assez légère contre l'usure et l'oxydation, ainsi qu'une protection anticorrosion des roulements dans les moteurs fonctionnant dans des conditions de faible charge. Les huiles moteur de cette classe ne peuvent être utilisées que si elles sont spécifiquement recommandées par le constructeur du moteur.

API classe SA- huiles moteur pour moteurs essence et diesel. Une classe obsolète d'huiles à utiliser dans les anciens moteurs fonctionnant dans des conditions et des modes dans lesquels la protection des pièces avec des additifs n'est pas nécessaire. Les huiles moteur de cette classe ne peuvent être utilisées que si elles sont recommandées par le constructeur du moteur.

Classes de qualité API pour les moteurs diesel

Classe API CJ-4- à compter du 1er octobre 2006.
Cette classe est conçue spécifiquement pour les moteurs lourds. Répond aux principales exigences en matière d'émissions de NOx et de particules pour les moteurs 2007. Des limites sont introduites sur les huiles CJ-4 pour certains indicateurs : la teneur en cendres est inférieure à 1,0 %, le soufre à 0,4 %, le phosphore à 0,12 %.
La nouvelle classification répond aux exigences des anciennes catégories API CI-4 PLUS, CI-4, mais introduit des modifications importantes aux exigences en réponse aux besoins des nouveaux moteurs qui répondent aux nouvelles normes d'émission 2007 et ultérieures.

Classe API CI-4 (CI-4 PLUS)- une nouvelle classe opérationnelle d'huiles moteur pour moteurs diesel. Par rapport à l'API CI-4, les exigences en matière de teneur en suie spécifique, ainsi que de volatilité et d'oxydation à haute température, sont augmentées. Lorsqu'elle est certifiée dans cette classification, l'huile moteur doit être testée dans dix-sept essais moteur.

Classe API CI-4- la classe a été introduite en 2002.
Ces huiles moteur sont utilisées dans les moteurs diesel modernes avec divers types injection et suralimentation. Une huile moteur qui répond à ce grade doit contenir des additifs détergents et dispersants appropriés et, par rapport au grade CH-4, a une résistance accrue à l'oxydation thermique, ainsi que des propriétés dispersantes plus élevées. De plus, ces huiles moteur permettent une réduction significative des déchets d'huile moteur en réduisant la volatilité et en réduisant l'évaporation à des températures de fonctionnement allant jusqu'à 370 ° C, sous l'influence des gaz. Les exigences de pompabilité à froid ont également été renforcées, la ressource en jeux, tolérances et joints moteur a été augmentée en améliorant la fluidité de l'huile moteur.
La classe API CI-4 a été introduite dans le cadre de l'émergence de nouvelles exigences plus strictes pour l'environnement et la toxicité des gaz d'échappement, qui s'appliquent aux moteurs fabriqués à partir du 1er octobre 2002.

Classe API CH-4- à compter du 1er décembre 1998.
Les huiles moteur de cette classe sont utilisées dans les moteurs diesel à quatre temps qui fonctionnent à grande vitesse et répondent aux exigences des normes et normes d'émission de 1998.
Les huiles moteur API CH-4 répondent aux exigences assez strictes des fabricants de moteurs diesel américains et européens. Les exigences de classe sont spécifiquement conçues pour une utilisation dans des moteurs fonctionnant avec des carburants de haute qualité avec une teneur en soufre spécifique allant jusqu'à 0,5 %. Dans le même temps, contrairement à la classe API CG-4, la ressource de ces huiles moteur est moins sensible à l'utilisation de carburant diesel avec une teneur en soufre supérieure à 0,5%, ce qui est particulièrement important pour les pays d'Amérique du Sud, d'Asie , et l'Afrique.
Les huiles moteur API CH-4 répondent à des exigences accrues et doivent contenir des additifs qui empêchent plus efficacement l'usure des soupapes et la formation de dépôts de carbone sur les surfaces internes. Elles peuvent être utilisées comme substituts des huiles moteur API CD, API CE, API CF-4 et API CG-4 conformément aux recommandations du constructeur du moteur.

Classe API CG-4- la classe a été introduite en 1995.
Les huiles moteur de cette classe sont recommandées pour les moteurs diesel à quatre temps des autobus, camions et tracteurs de type ligne principale et non principale, qui fonctionnent en mode charge élevée et vitesse élevée. L'huile moteur API CG-4 convient aux moteurs qui utilisent des carburants de haute qualité avec une teneur en soufre spécifique ne dépassant pas 0,05%, ainsi qu'aux moteurs pour lesquels il n'y a pas d'exigences particulières en matière de qualité du carburant (la teneur en soufre spécifique peut atteindre 0,5% ).
Les huiles automobiles certifiées selon la classe API CG-4 devraient prévenir plus efficacement l'usure des pièces internes du moteur, la formation de dépôts sur les surfaces internes et les pistons, l'oxydation, le moussage et la formation de suie (ces propriétés sont particulièrement nécessaires pour les moteurs de longue distance modernes). bus et tracteurs).
La classe API CG-4 a été créée dans le cadre de l'approbation aux États-Unis de nouvelles exigences et normes pour l'écologie et la toxicité des gaz d'échappement (révisées en 1994). Les huiles moteur de cette classe peuvent être utilisées dans les moteurs pour lesquels les classes API CD, API CE et API CF-4 sont recommandées. Le principal inconvénient qui limite l'utilisation massive des huiles moteur de cette classe, par exemple, en Europe de l'Est et en Asie, est la dépendance importante de la ressource en huile moteur à la qualité du carburant utilisé.

Classe API CF-2 (CF-II)- huiles moteur conçues pour être utilisées dans les moteurs diesel à deux temps qui fonctionnent dans des conditions difficiles.
La classe a été introduite en 1994. Les huiles moteur de cette classe sont généralement utilisées dans les moteurs diesel à deux temps qui fonctionnent sous des contraintes accrues. Les huiles API CF-2 doivent contenir des additifs qui offrent une meilleure protection des performances contre l'usure des pièces internes du moteur telles que les cylindres et les segments. De plus, ces huiles moteur doivent empêcher l'accumulation de dépôts sur les surfaces internes du moteur (fonction de nettoyage améliorée).
L'huile moteur certifiée API CF-2 a des propriétés améliorées et peut être utilisée à la place d'anciennes huiles similaires, sous réserve des recommandations du fabricant.

Classe API CF-4- huiles moteur à utiliser dans les moteurs diesel à quatre temps depuis 1990.
Les huiles moteur de cette classe peuvent être utilisées dans les moteurs diesel à quatre temps, dont les conditions de fonctionnement sont associées à des modes à grande vitesse. Dans de telles conditions, les exigences de qualité de l'huile dépassent les capacités de la classe CE, de sorte que les huiles moteur CF-4 peuvent être utilisées à la place des huiles de classe CE (s'il existe des recommandations appropriées du fabricant du moteur).
Les huiles moteur API CF-4 doivent contenir des additifs appropriés qui offrent une réduction de la combustion de l'huile de voiture, ainsi qu'une protection contre les dépôts de carbone dans le groupe de pistons. L'objectif principal des huiles moteur de cette classe est l'utilisation dans les moteurs diesel de tracteurs lourds et d'autres véhicules utilisés pour de longs trajets sur les autoroutes.
De plus, ces huiles moteur se voient parfois attribuer le double grade API CF-4/S. Dans ce cas, sous réserve de la disponibilité des recommandations pertinentes du constructeur du moteur, ces huiles moteur peuvent également être utilisées dans les moteurs à essence.

Classe API CF (CF-2, CF-4)- huiles moteur pour moteurs diesel à injection indirecte. Les classes ont été introduites de 1990 à 1994. Un nombre composé d'un trait d'union signifie un moteur à deux ou quatre temps.
La classe CF décrit les huiles moteur recommandées pour une utilisation dans les moteurs diesel à injection indirecte, ainsi que d'autres types de moteurs diesel fonctionnant au carburant qualité différente, y compris ceux à forte teneur en soufre (par exemple, plus de 0,5 % de la masse totale).
Les huiles moteur certifiées CF contiennent des additifs pour améliorer la prévention des dépôts sur les pistons, de l'usure et de la corrosion des roulements en cuivre (contenant du cuivre), qui sont importants pour ces types de moteurs, et peuvent être pompées de manière conventionnelle, ainsi qu'avec un turbocompresseur ou compresseur. Les huiles moteur de ce grade peuvent être utilisées lorsque la qualité CD est recommandée.

Classe API CE- huiles moteur destinées à être utilisées dans les moteurs diesel depuis 1983 (classe obsolète).
Les huiles de voiture de cette classe étaient destinées à être utilisées dans certains moteurs turbocompressés à usage intensif, caractérisés par une compression de travail considérablement accrue. L'utilisation de telles huiles était autorisée pour les moteurs à vitesse d'arbre faible et élevée.
Les huiles moteur API CE sont recommandées pour les moteurs diesel à basse et haute vitesse fabriqués depuis 1983 qui fonctionnent dans des conditions difficiles. Sous réserve de la disponibilité des recommandations pertinentes du fabricant du moteur, ces huiles moteur pourraient également être utilisées dans les moteurs pour lesquels des huiles moteur de classe CD étaient recommandées.

Classe API CD-II- huiles moteur destinées aux moteurs diesel de grande puissance à cycle de travail à deux temps (classe obsolète).
La classe a été introduite en 1985 pour une utilisation dans les moteurs diesel à deux temps et est, en fait, un développement évolutif de la classe API CD précédente. Le but principal de l'utilisation de ces huiles moteur était l'utilisation dans des moteurs diesel lourds et puissants, qui étaient installés principalement sur des machines agricoles. Les huiles moteur de cette classe répondent à toutes les normes de travail de la classe CD précédente. De plus, les exigences en matière de protection très efficace du moteur contre les dépôts de carbone et l'usure ont été considérablement augmentées.

Classe d'API CD- huiles moteur pour moteurs diesel de puissance accrue, qui étaient utilisés dans les machines agricoles (classe obsolète). La classe a été introduite en 1955 pour une utilisation générale dans certains moteurs diesel, à la fois atmosphériques et turbocompressés, avec une compression accrue des cylindres, où une protection efficace contre les dépôts de carbone et l'usure est essentielle. Les huiles moteur de cette classe pourraient être utilisées dans les cas où le constructeur du moteur n'a pas proposé d'exigences supplémentaires pour la qualité du carburant (y compris le carburant à haute teneur en soufre).
Les huiles moteur API CD étaient censées offrir une protection accrue contre la corrosion des roulements et la suie à haute température dans les moteurs diesel par rapport aux classes précédentes. Souvent, les huiles moteur de cette classe étaient appelées "Caterpillar Series 3", en raison du fait qu'elles répondaient aux exigences de la certification Superior Lubricants (Series 3) développée par Caterpillar Tractor Company.

Classe API CC- huiles moteur pour moteurs diesel fonctionnant dans des conditions de charge moyenne (classe obsolète).
La classe a été introduite en 1961 pour être utilisée dans certains moteurs, atmosphériques et turbocompressés, qui se caractérisaient par une compression accrue. Les huiles moteur de cette classe étaient recommandées pour les moteurs fonctionnant en modes de charge modérée et élevée.
De plus, sous réserve des recommandations du constructeur du moteur, de telles huiles moteur pourraient être utilisées dans certains moteurs à essence puissants.
Par rapport aux grades précédents, les huiles moteur API CC devaient fournir un niveau de protection plus élevé contre les dépôts à haute température et la corrosion des roulements dans les moteurs diesel, ainsi que contre la rouille, la corrosion et les dépôts à basse température dans les moteurs à essence.

Classe API CB- huiles moteur pour moteurs diesel fonctionnant à charge moyenne (classe obsolète).
La classe a été approuvée en 1949 en tant que développement évolutif de la classe CA utilisant du carburant à haute teneur en soufre sans exigences de qualité particulières. Les huiles moteur API CB étaient également destinées à être utilisées dans des moteurs suralimentés qui fonctionnaient dans des conditions légères et modérées. Ce grade était souvent appelé "huiles moteur annexe 1" pour indiquer la conformité à la réglementation militaire MIL-L-2104A annexe 1.

Autorité de certification de classe API- huiles moteur pour moteurs diesel peu chargés (classe obsolète).
Les huiles de voiture de cette classe sont conçues pour être utilisées dans les moteurs diesel fonctionnant dans des conditions légères et modérées avec du carburant diesel de haute qualité. Conformément aux recommandations des constructeurs automobiles, ils peuvent également être utilisés dans certains moteurs à essence fonctionnant dans des conditions modérées.
La classe a été largement utilisée dans les années 40 et 50 du siècle dernier et ne peut être utilisée dans les conditions modernes que si le fabricant du moteur l'exige.
Les huiles moteur API CA doivent avoir des propriétés de protection contre les dépôts de carbone sur les segments de piston, ainsi que contre la corrosion des roulements dans les moteurs suralimentés, pour lesquels il n'y a pas d'exigences particulières quant à la qualité du carburant utilisé.

Dans cet article, j'ai essayé de collecter des informations pouvant être utiles aux testeurs qui souhaitent savoir ce qu'est l'API. J'espère que les personnes expérimentées dans les tests d'API trouveront également quelque chose d'utile pour elles-mêmes. Eh bien, ou au moins aider à trouver des erreurs dans mon article :)
Qu'est-ce que l'API ?

API (Application Programming Interface) - un ensemble de classes, procédures, fonctions, structures et constantes prêtes à l'emploi fournies par une application (bibliothèque, service) à utiliser dans des produits logiciels externes (Wikipedia).

En d'autres termes, l'API nous donne la possibilité d'utiliser les développements d'autres personnes à nos propres fins. Pour la première fois, je suis tombé sur une API utilisant l'API Windows comme exemple. Il s'agit d'un ensemble de fonctions que toute application exécutée sur un système d'exploitation donné peut utiliser. Par exemple, il peut utiliser des fonctions standard pour dessiner l'interface.

Les API modernes prennent souvent la forme de services Web qui fournissent aux utilisateurs (humains et autres services Web) un certain type d'informations. Habituellement, la procédure d'échange d'informations et le format de transfert de données sont structurés de manière à ce que les deux parties sachent comment interagir l'une avec l'autre.

Sur le site https://dev.hh.ru/ (plus précisément, https://github.com/hhru/api/blob/master/docs/general.md) vous pouvez trouver une description de la façon dont les clients de l'API HeadHunter et les services interagissent entre eux. Par exemple, une citation du site :

• Toutes les API fonctionnent sur le protocole HTTPS.
• L'autorisation est effectuée à l'aide du protocole OAuth2.
• Toutes les données sont uniquement disponibles au format JSON.
• URL de base — https://api.hh.ru/
• Les dates sont au format ISO 8601 : AAAA-MM-JJThh:mm:ss±hhmm

Formats de transfert de données

Il existe de nombreux formats de données que les utilisateurs utilisent pour interagir avec l'API. Par exemple, le célèbre XML. Ou JSON - un format léger et simple qui ressemble à :

( "id": "0001", "type": "beignet", "nom": "Gâteau", "image": ( "url": "images/0001.jpg", "largeur": 200, "hauteur " : 200) ) P à propos de ss Dans les liens ci-dessous, vous pouvez voir les réponses provenant de MediaWikiAPI , sous différents formats :

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 ( avec attention, se produire avec bascule dossier)

httpg lagos

Généralement P Lors de l'accès à l'API Webutilisant Les requêtes HTTP sont envoyées . C'est pourquoiau moins brièvement sur les méthodes standards, qui peut être contenu dans Requête HTTP . Ces méthodes également appelés verbes HTTP :

• OBTENIR. Probablement le type le plus populaire demande. Utilisé pour recevoir ou lire des données.
• METTRE. Habituel n Oh et spo Utilisé pour mettre à jour une ressource .
• PUBLIER. Généralement utilisé pour créer une nouvelle ressource.
• EFFACER. Supprime les données.
• Et d'autres

Si nous voulons mettre à jour une ressource - nous pouvons envoyer une requête PUT :
METTRE http://www.example.com/customers/12345/orders/98765

Les requêtes GET normales peuvent être envoyées par un navigateur Web. L'envoi d'autres types de requêtes peut nécessiter des langages de script ou outils spéciaux(plus à ce sujet ci-dessous).

À propos de HTTP les méthodes peuvent être lues plus en détail à sur W iki.

http à l'ode des réponses

Le serveur peut envoyer différents codes en réponse aux demandes des utilisateurs. Il peut s'agir de codes d'erreur ou simplement de codes informant les utilisateurs de l'état du serveur. Description détaillée peut être trouvé, encore une fois, sur le wiki.

Les codes les plus connus sont 4xx (problèmes côté client) et 5xx (problèmes côté serveur). Les développeurs de l'API décident eux-mêmes quels codes renvoyer dans une situation donnée. Par exemple, l'API du site Web d'Odnoklassniki renvoie des codes dont la description se trouve sur la page https://apiok.ru/wiki/pages/viewpage.action?pageId=77824003 .

De plus, je vous conseille d'écouter la chanson Request-response - simple et claire sur les codes retournés dans les requêtes HTTP (attention, repchik :)).

API REST - c'est l'idéologie de la poste fourmillement API, qui signifieTransfert d'État représentatif API. Il est basé sur les principes suivants formulés par son créateur , Roy Fielding:

1. Architecture client-serveur
2. Serveur sans état
3. capacité de cache
4. Structure multicouche
5. Interface unique
6. Code à la demande

API Windows - ensemble de fonctionnalités système opérateur

L'abréviation API semble à de nombreux programmeurs novices être très mystérieuse et même effrayante. En fait, l'interface de programmation d'applications (API) n'est qu'un ensemble de fonctions prêtes à l'emploi que les développeurs d'applications peuvent utiliser. En général, ce concept équivaut à ce qu'on appelait plus souvent une bibliothèque de sous-programmes. Cependant, l'API est généralement comprise comme une catégorie spéciale de ces bibliothèques.

Lors du développement de presque toutes les applications plutôt complexes (MyApplication), un ensemble de fonctions internes spécifiques est formé pour l'utilisateur final, qui est utilisé pour implémenter ce programme particulier, appelé API MyApplication. Cependant, il s'avère souvent que ces fonctions peuvent être utilisées efficacement pour créer d'autres applications, y compris d'autres programmeurs. Dans ce cas, les auteurs, en fonction de la stratégie de promotion de leur produit, doivent décider s'ils ouvrent ou non l'accès à cet ensemble à des utilisateurs externes ? Si la réponse est oui, dans la description du progiciel, la phrase apparaît comme une caractéristique positive : "Le progiciel comprend un ensemble ouvert de fonctions API" (mais parfois moyennant de l'argent supplémentaire).

Ainsi, le plus souvent, une API fait référence à un ensemble de fonctions qui font partie d'une application, mais en même temps disponibles pour une utilisation dans d'autres programmes. Par exemple, Excel, en plus de l'interface pour l'utilisateur final, dispose d'un ensemble Fonctions Excel Une API qui peut être utilisée, en particulier, lors de la construction d'applications avec VB.

En conséquence, l'API Windows est un ensemble de fonctions faisant partie du système d'exploitation lui-même et en même temps disponible pour toute autre application, y compris celles écrites avec VB. A cet égard, l'analogie avec l'ensemble interruptions du système BIOS/DOS, qui est en fait une API DOS.

La différence réside dans le fait que la composition des fonctions de l'API Windows, d'une part, est beaucoup plus large que sous DOS, d'autre part, elle n'inclut pas de nombreux outils de gestion directe des ressources informatiques qui étaient disponibles pour programmeurs dans le système d'exploitation précédent. De plus, l'accès à l'API Windows est effectué à l'aide d'appels procéduraux ordinaires et les fonctions DOS sont appelées via une instruction machine spéciale du processeur, appelée Interrupt ("interruption").

Pourquoi avez-vous besoin de l'API Win pour les programmeurs VB

Malgré le fait que VB possède une grande variété de fonctions, en cours de développement plus ou moins sérieux, il s'avère que leurs capacités ne sont souvent pas suffisantes pour résoudre les tâches nécessaires. Dans le même temps, les programmeurs novices commencent souvent à se plaindre des lacunes de VB et pensent à changer d'outils, sans se douter que leur ordinateur dispose d'un vaste ensemble d'outils et qu'il vous suffit de savoir les utiliser.

Lorsque vous vous familiarisez avec l'API Win, il s'avère que de nombreuses fonctions VB intégrées ne sont rien de plus qu'un appel aux procédures système correspondantes, mais uniquement implémentées sous forme de syntaxe langue donnée. Dans cette optique, la nécessité d'utiliser l'API est déterminée par les options suivantes :

1. Fonctions API entièrement implémentées en tant que fonctions VB intégrées. Néanmoins, parfois dans ce cas, il est utile de passer à l'utilisation de l'API, car cela peut parfois améliorer considérablement les performances (notamment en raison de l'absence de conversions inutiles des paramètres passés).
2. Les fonctions VB intégrées n'implémentent qu'un cas particulier de la fonction API correspondante. C'est une option assez courante. Par exemple, l'API CreateDirectory est plus puissante que l'instruction VB MkDir intégrée.
3. Un grand nombre de fonctions API n'ont aucun analogue dans la version actuelle du langage VB. Par exemple, vous ne pouvez pas supprimer un répertoire à l'aide de VB - vous devez utiliser la fonction DeleteDirectory pour ce faire.

Il convient également de souligner que certaines fonctions API (leur part dans l'API Win est très faible) ne peuvent pas être appelées à partir de programmes VB en raison d'un certain nombre de restrictions linguistiques, par exemple en raison de l'impossibilité de travailler avec des adresses mémoire. Mais dans certains cas, des techniques de programmation non triviales peuvent aider (en particulier, dans le cas des mêmes adresses).

Le point de vue personnel de l'auteur est qu'au lieu d'étendre de version en version les fonctions intégrées de VB, il faudrait donner bonne description les fonctions API les plus populaires. En même temps, je voudrais conseiller aux développeurs de ne pas attendre l'apparition nouvelle version outils avec des fonctions avancées, et pour examiner de plus près la composition de l'API Win existante - il est probable que les fonctionnalités dont vous avez besoin pourraient déjà être implémentées dans la version VB 1.0 de la version 1991.

Comment apprendre l'API Win

Ce n'est pas une question si simple, étant donné que le nombre de fonctions de l'API Win32 est estimé à environ 10 000 (personne ne connaît le nombre exact, pas même Microsoft).

VB (versions 4-6) inclut un fichier avec une description des déclarations de l'API Win - WIN32API.TXT (plus sur son utilisation plus tard). Mais, d'une part, il ne peut être utilisé pour obtenir des informations sur le but d'une fonction particulière et ses paramètres que par les noms mnémoniques utilisés, et d'autre part, la liste des fonctions de ce fichier est loin d'être complète. À un moment donné (il y a sept ans), VB 3.0 avait des fichiers d'aide spéciaux décrivant les fonctions de l'API Win16. Cependant, déjà dans la v.4.0, ces informations utiles avec une interface pratique ont disparu.

Des informations complètes sur l'API Win32 sont disponibles dans système d'aide Platform Software Development Kit, qui se trouve notamment sur les CD MSDN Library inclus avec VB 5.0 et 6.0 Enterprise Edition et Office 2000 Developer Edition. Cependant, il n'est pas facile d'y trouver les informations nécessaires et de les comprendre. Sans oublier le fait que toutes les descriptions y sont données en relation avec le langage C.

Le guide de renommée mondiale pour apprendre la programmation API dans l'environnement VB est les livres du célèbre expert américain Daniel Appleman. Sa série Visual Basic Programmer's Guide to the Windows API de Dan Appleman (pour Win16, Win32, appliqué à différentes versions VB) est l'un des best-sellers des programmeurs VB depuis 1993. Le Guide du programmeur VB 5.0 de Dan Appleman pour l'API Win32, publié en 1997, a été apporté à l'auteur des États-Unis par un ami qui l'a trouvé dans la première librairie d'une petite ville de province.

Ce livre compte plus de 1 500 pages et comprend des techniques générales de programmation d'API VB, ainsi que plus de 900 fonctions. Le CD-ROM qui l'accompagne contient le texte intégral du livre et tous les exemples de programmation, ainsi que quelques chapitres supplémentaires non inclus dans la version imprimée. En 1999, Dan Appleman a publié nouveau livre Le livre de puzzle et didacticiel de l'API Win32 de Dan Appleman pour les programmeurs Visual Basic, qui comprend des informations sur 7600 autres fonctions (mais pas aussi étendues).

API Win et bibliothèque de liens dynamiques (DLL)

L'ensemble d'API Win est implémenté sous forme de DLL dynamiques. De plus, nous parlerons en fait de la technologie d'utilisation des DLL dans l'environnement VB en utilisant l'exemple des bibliothèques qui font partie de l'API Win. Cependant, lorsque l'on parle de DLL, il y a quelques points importants à noter.

Dans ce cas, par DLL, nous entendons la variante traditionnelle des bibliothèques dynamiques binaires, qui fournissent aux applications un accès direct aux procédures nécessaires - sous-routines ou fonctions (un peu comme cela se produit lors de l'appel de procédures dans un projet VB). De telles bibliothèques peuvent être créées à l'aide de différents outils : VC++, Delphi, Fortran, à l'exception de VB (nous verrons ce qui apparaîtra dans la version 7.0) - ce dernier ne peut créer que des DLL ActiveX, accessibles via l'interface OLE Automation.

En règle générale, les fichiers de bibliothèque de liens dynamiques ont une extension .DLL, mais ce n'est pas du tout nécessaire (pour Win16, l'extension .EXE était souvent utilisée) ; Les pilotes de périphériques externes sont identifiés par .DRV.

Comme nous l'avons déjà noté, il est assez difficile de déterminer le nombre exact d'API Windows et les fichiers qui les contiennent, mais ils sont tous situés dans le répertoire système. À cet égard, il est préférable de distinguer la composition des bibliothèques incluses dans le noyau du système d'exploitation et les principales bibliothèques avec des fonctions supplémentaires clés.

Et maintenant quelques conseils.

Conseil 1 : Assurez-vous que votre annonce DL est correctement formatée Procédures L

L'appel même aux procédures DLL dans le programme ressemble exactement à celui des procédures Visual Basic "normales", par exemple :

Appelez DllName([liste d'arguments])

Cependant, pour utiliser des fonctions DLL externes (y compris l'API Win), elles doivent être déclarées dans le programme à l'aide de l'instruction Declare, qui ressemble à ceci :

Déclarer Sub LibProcedureName _ "LibraryName" _ [([ArgumentList])]

Déclarer la fonction FunctionName _ Lib "LibraryName" _ [([ArgumentList])]

Ici, les éléments optionnels de l'opérateur sont donnés entre crochets, les variables d'expression sont en italique, le reste des mots sont des mots clés. Le système d'aide a une assez bonne description de la syntaxe de l'opérateur, donc pour l'instant nous allons juste faire quelques remarques.

Les déclarations de fonctions externes doivent être placées dans la section Déclarations générales du module. Si vous le placez dans un module de formulaire, vous devez spécifier le mot-clé Private (cette déclaration ne sera disponible qu'à l'intérieur de ce module) - c'est la restriction pour toutes les procédures du module de formulaire.

L'ensemble d'API Win32 est implémenté uniquement en tant que fonctions (l'API Win16 avait beaucoup de sous-routines). Ce sont pour la plupart des fonctions de type Long, qui renvoient le plus souvent le code de fin d'opération.

L'instruction Declare est apparue dans MS Basic à l'époque de DOS, et elle a également été utilisée pour déclarer les procédures internes du projet. En Visual Basic, ce n'est pas obligatoire, puisque la déclaration des procédures internes est automatiquement leur déclaration Sub ou Function. Par rapport à Basic/DOS, il est obligatoire de préciser dans la nouvelle description le nom du fichier bibliothèque où se trouve la procédure recherchée. Les bibliothèques de l'API Wip sont situées dans le répertoire système de Windows, il suffit donc de ne donner que le nom du fichier. Si vous accédez à une DLL située à un emplacement arbitraire, vous devez noter le chemin d'accès complet à ce fichier.

La description de l'instruction Declare prend généralement beaucoup d'espace et ne tient pas sur une seule ligne dans la fenêtre de code. Par conséquent, nous vous recommandons de suivre un schéma de saut de ligne spécifique lors de l'écriture d'applications, par exemple :

Déclarez la fonction GetTempPath _ Lib "kernel32" Alias ​​"GetTempPathA" _ (ByVal nBufferLength As Long, _ ByVal lpBuffer As String) As Long

Dans ce cas, tous les éléments principaux de la description sont séparés en différentes lignes et sont donc bien lus.

Astuce 2 : Soyez particulièrement prudent lorsque vous travaillez avec des fonctions DLL

L'utilisation de l'API Win et de diverses fonctions DLL étend considérablement les fonctionnalités de VB et améliore souvent les performances des programmes. Cependant, cela a pour conséquence le risque de réduire la fiabilité de l'application, en particulier lors du processus de débogage.

L'un des avantages les plus importants de l'environnement VB est la fiabilité du processus de développement du programme : fonctionnant sous le contrôle de l'interpréteur, le code du programme ne peut théoriquement pas violer Travail Windows et VB lui-même. Le programmeur peut ne pas être très attentif à l'exactitude de la transmission des paramètres aux fonctions appelées - de telles erreurs seront facilement détectées par l'interpréteur lui-même, soit lors du processus de traduction du code, soit lors de son exécution. Dans le cas le plus désagréable, le mode de traitement sera simplement interrompu, et avec une indication de l'endroit et de la raison de l'erreur.

L'utilisation directe des fonctions de l'API Windows ou d'autres DLL supprime ce contrôle sur le transfert de données et l'exécution de code en dehors de l'environnement VB. Par conséquent, une erreur d'accès aux fonctions externes peut entraîner l'inopérabilité de VB et du système d'exploitation. Cela est particulièrement vrai au stade du développement du programme, lorsque la présence d'erreurs est tout à fait naturelle. Ainsi, en appliquant les possibilités plus larges des fonctions de la couche de base du système, le programmeur assume la responsabilité de l'exactitude de leur application.

Le problème est exacerbé par le fait que différents langages de programmation utilisent différentes manières de passer des paramètres entre les procédures. (Plus précisément, différentes façons les passes sont la valeur par défaut, car de nombreux langages peuvent prendre en charge plusieurs méthodes.) Les API Win sont implémentées en C/C++ et utilisent des conventions de passage de paramètres C/C++, qui sont différentes de celles auxquelles VB est habitué.

A cet égard, il convient de noter que l'apparition d'analogues de fonctions API intégrées à VB se justifie par l'adaptation de cette dernière à la syntaxe VB et la mise en place du mécanisme de contrôle des échanges de données correspondant. Notez également qu'au stade du débogage expérimental de l'application, lors de la création d'un module exécutable, il est préférable d'utiliser l'option de compilation P-code au lieu de Native Code (code machine). Dans le premier cas, le programme s'exécutera sous le contrôle d'un interpréteur - plus lent que le code machine, mais plus fiable en termes d'éventuels effets erronés sur le système d'exploitation et offrant un mode plus pratique pour détecter d'éventuelles erreurs.

Astuce 3 : Les dix astuces de Dan Appleman pour une programmation d'API fiable en VB

L'utilisation d'une fonction API nécessite une programmation plus minutieuse, en utilisant certaines des méthodes d'appel de procédures les moins familières (par rapport à VB). Nous continuerons à aborder ces questions dans ce qui suit. Et voici maintenant un résumé des conseils de Dan Appleman sur ce sujet (leur première version est parue en 1993), avec quelques-uns de nos ajouts et commentaires.

1. Rappelez-vous ByVal. Plus erreur commune, effectué lors de l'accès aux fonctions API et DLL, est l'utilisation incorrecte de mot-clé ByVal : soit ils oublient de le mettre, soit au contraire le mettent alors que ce n'est pas nécessaire.

Ces exemples montrent l'effet de l'instruction ByVal sur le passage de paramètres

Rappelons ici que le transfert de paramètres dans tout système de programmation, y compris VB, s'effectue de deux manières principales : par référence (ByRef) ou par valeur (ByVal). Dans le premier cas, l'adresse de la variable est transmise (cette option est utilisée par défaut dans VB), dans le second - sa valeur. La différence fondamentale réside dans le fait qu'à l'aide d'une référence, la valeur modifiée du paramètre passé est renvoyée au programme appelant.

Pour comprendre cela, menez une expérience en utilisant les programmes suivants :

Dim v As Integer v = 2 Call MyProc(v) MsgBox "v = " & v Sub MyProc (v As Integer) v = v + 1 End Sub

Lorsque vous exécuterez cet exemple, vous recevrez un message avec la valeur de la variable égale à 3. Le fait est que dans ce cas, l'adresse de la variable v, créée physiquement dans le programme appelant, est passée au sous-programme MyProc. Changez maintenant la description de la procédure en

Sub MyProc (ByVal v As Integer)

Par conséquent, lorsque vous exécutez le test, vous obtenez v = 2, car seule la valeur initiale de la variable est transmise à la procédure - le résultat des opérations effectuées dessus n'est pas renvoyé au programme appelant. Vous pouvez également modifier le mode de passage par valeur à l'aide de l'instruction Call comme suit :

Sub MyProc (v As Integer) ... Call MyProc((v)) ‘ (v) - les parenthèses indiquent le mode de passage par valeur _.

Toutefois, lorsque vous faites référence à des procédures VB internes, l'utilisation du mot clé ByVal dans l'instruction Call est interdite - des parenthèses sont utilisées à la place. Cela a sa propre explication.

Dans le cas classique (C, Fortran, Pascal), la différence entre les modes ByRef et ByVal dépend de ce qui est exactement placé sur la pile d'échange de données - l'adresse de la variable ou sa valeur. Basic utilise historiquement une variante de l'émulation logicielle ByVal - l'adresse est toujours sur la pile, mais uniquement lors du passage par valeur, une variable temporaire est créée à cet effet. Pour distinguer ces deux options (classique et basique), différentes manières de décrire le mode ByVal sont utilisées. A noter que l'émulation du mode ByVal en VB permet une plus grande fiabilité du programme : en confondant la forme de l'appel, le programmeur risque seulement que la valeur corrigée de la variable soit renvoyée (ou non renvoyée) au programme appelant. Dans la version "classique", une telle confusion peut conduire à erreur fatale lorsqu'une procédure est exécutée (par exemple, lorsqu'une valeur de variable égale à, disons, zéro sera utilisée à la place d'une adresse mémoire).

Les fonctions DLL sont implémentées selon des principes "classiques" et nécessitent donc une description obligatoire de la façon dont les données sont échangées avec chacun des arguments. C'est le but des déclarations de fonctions via la description Declare (plus précisément, la liste des arguments passés). Le moyen le plus courant de transmettre des paramètres à une API Windows ou à une fonction DLL consiste à utiliser le mot clé ByVal. De plus, il peut être défini à la fois dans l'instruction Declare et directement lors de l'appel de la fonction.

Les conséquences d'un passage incorrect des paramètres sont faciles à prévoir. Si vous recevez une adresse manifestement invalide, vous recevrez un message GPF (General Protection Fault). Si la fonction reçoit une valeur qui correspond à une adresse valide, la fonction API rampera dans la zone de quelqu'un d'autre (par exemple, dans le noyau Windows) avec toutes les conséquences catastrophiques qui en découlent.

2. Vérifiez le type des paramètres passés. Le nombre et le type corrects de paramètres transmis sont tout aussi importants. Les arguments déclarés dans Declare doivent correspondre aux paramètres attendus dans la fonction API. Le cas le plus courant d'erreur dans le passage des paramètres est lié à la différence entre NULL et une chaîne de longueur nulle - rappelez-vous qu'ils ne sont pas la même chose.

3. Vérifiez le type de retour.

VB est assez tolérant aux incompatibilités de type de retour. fonction valeur, car les valeurs numériques sont généralement renvoyées via des registres, et non via la pile. Les règles suivantes vous aideront à déterminer la valeur correcte renvoyée par une fonction API :

• Une fonction DLL qui ne renvoie pas de valeur (analogue à void en 'C') doit être déclarée en tant que VB Sub.
• une fonction API qui renvoie une valeur entière (Integer ou Long) peut être définie comme un Sub ou une Function qui renvoie une valeur du type approprié.
• aucune des fonctions de l'API ne renvoie de nombres à virgule flottante, mais certaines DLL peuvent très bien renvoyer un tel type de données.

4. Utilisez la construction "As Any" avec beaucoup de soin. De nombreuses fonctions de l'API Windows ont la capacité d'accepter des paramètres de différents types et d'utiliser la construction As Any (l'interprétation du type est effectuée en fonction de la valeur des autres paramètres transmis).

Une bonne solution dans ce cas serait d'utiliser plusieurs alias de fonction, en créant deux déclarations ou plus pour la même fonction, chaque déclaration spécifiant des paramètres d'un type particulier.

5. N'oubliez pas d'initialiser les chaînes. Il existe de nombreuses fonctions dans l'API Win qui renvoient des informations en chargeant des données dans des tampons de chaîne passés en paramètre. Dans votre programme, vous pouvez sembler tout faire correctement : n'oubliez pas ByVal, passez correctement les paramètres à la fonction. Mais Windows ne peut pas vérifier la taille de la mémoire allouée à la chaîne. La ligne doit être suffisamment grande pour contenir toutes les données qui peuvent y être placées. Il est de la responsabilité du programmeur VB de réserver un tampon de taille correcte.

Notez que sur Windows 32 bits, les chaînes sont converties d'Unicode (codage à deux octets) en ANSI (un octet) et vice versa, en tenant compte des paramètres nationaux du système. Par conséquent, pour réserver des tampons, il est parfois plus pratique d'utiliser des tableaux d'octets au lieu de variables de chaîne. (Plus d'informations à ce sujet seront discutées ci-dessous.)

Le plus souvent, les fonctions de l'API Win vous permettent de définir vous-même la taille maximale des blocs. En particulier, cela nécessite parfois d'appeler une autre fonction API qui "demandera" la taille du bloc. Par exemple, GetWindowTextLength vous permet de déterminer la taille de la chaîne requise pour contenir le titre de la fenêtre renvoyé par la fonction GetWindowText. Dans ce cas, Windows s'assure que vous ne sortez pas des limites.

6. Assurez-vous d'utiliser l'option explicite.

7. Vérifiez soigneusement les valeurs des paramètres et les valeurs de retour. VB a de bonnes capacités de vérification de type. Cela signifie que lorsque vous essayez de passer un paramètre invalide à une fonction VB, la pire chose qui puisse arriver est que vous obteniez un message d'erreur de VB. Mais ce mécanisme, malheureusement, ne fonctionne pas lors de l'accès aux fonctions de l'API Windows.

Windows 9x dispose d'un système de vérification des paramètres amélioré pour la plupart des fonctions de l'API. Par conséquent, la présence d'une erreur dans les données ne provoque généralement pas d'erreur fatale, mais il n'est pas si facile de déterminer ce qui l'a provoquée.

Ici, nous pouvons vous conseiller d'utiliser plusieurs méthodes pour déboguer ce type d'erreur :

• utilisez le débogage pas à pas ou la commande Debug.Print pour inspecter chaque appel de fonction API suspect. Vérifiez les résultats de ces appels pour vous assurer que tout va bien et que la fonction s'est correctement terminée ;
• utilisez un débogueur Windows comme CodeView et une version de débogage de Windows (fournie dans le SDK Windows). Ces outils peuvent détecter une erreur de paramètre et au moins déterminer quelle fonction API est à l'origine de l'erreur ;
• utiliser des outils tiers supplémentaires pour vérifier les types de paramètres et la validité de leurs valeurs. De tels outils peuvent non seulement trouver les erreurs de paramètres, mais aussi pointer vers la ligne de code VB où l'erreur s'est produite.

De plus, il est nécessaire de vérifier le résultat de l'exécution de la fonction API.

8. N'oubliez pas que les nombres entiers dans VB et dans Windows ne sont pas la même chose. Tout d'abord, vous devez garder à l'esprit que le terme "entier" dans VB fait référence à un nombre 16 bits, dans la documentation Win 32 - un nombre 32 bits. Deuxièmement, les nombres entiers (Integer et Long) dans VB sont des valeurs signées (c'est-à-dire qu'un bit est utilisé comme signe, le reste est utilisé comme mantisse d'un nombre), sous Windows, seuls des nombres non négatifs sont utilisés. Cette circonstance doit être gardée à l'esprit lorsque vous formez le paramètre passé à l'aide d'opérations arithmétiques (par exemple, calculez l'adresse en additionnant une base et un décalage). Les fonctions arithmétiques standard de VB ne conviennent pas pour cela. Comment être dans ce cas, nous parlerons séparément.

9. Portez une attention particulière aux noms de fonction. Contrairement à Win16, les noms de toutes les fonctions de l'API Win32 sont sensibles à l'utilisation exacte des lettres minuscules et majuscules (ce n'était pas le cas dans Win16). Si vous utilisez une minuscule au lieu d'une majuscule quelque part, ou vice versa, la fonction souhaitée ne sera pas trouvée. Faites également attention à l'utilisation correcte du suffixe A ou W dans les fonctions qui acceptent des paramètres de chaîne. (Pour en savoir plus, voir ci-dessous.)

10. Enregistrez souvent votre travail. Les erreurs liées à une utilisation incorrecte de la DLL et de l'API Win peuvent entraîner un plantage de l'environnement VB, voire de l'ensemble du système d'exploitation. Vous devez vous assurer que le code que vous écrivez avant l'exécution du test est enregistré. Le plus simple consiste à configurer les modules du projet pour qu'ils s'enregistrent automatiquement avant d'exécuter le projet dans VB.

Après avoir lu le conseil précédent, vous pourriez penser que l'utilisation des fonctions de l'API Win est une entreprise risquée. Dans une certaine mesure, cela est vrai, mais seulement en comparaison avec la programmation sécurisée fournie par VB lui-même. Mais avec leur application habile et leur connaissance des pièges possibles, ce risque est minime. De plus, il est souvent tout simplement impossible d'abandonner complètement l'utilisation de l'API Win - elles seront toujours nécessaires pour tout développement sérieux.

De plus, nous avons mentionné précédemment les "pièges" pour une large classe de DLL. Dans le cas de l'API Win, tout est beaucoup plus simple, puisque la forme d'appel de ces fonctions est clairement unifiée ici. Ce faisant, il convient de garder à l'esprit les points clés suivants :

1. Les fonctions de l'API Win32 sont exactement des fonctions, c'est-à-dire des procédures de type Function (il y avait de nombreuses sous-routines dans l'API Win16). Ce sont toutes des fonctions de type Long, donc leurs descriptions sont écrites comme suit : Declare Function name ... As Long ' le type de fonction _ est explicitement défini

   Déclarez le nom de la fonction & ' le type de fonction _ est défini avec le suffixe

   L'appel de la fonction API ressemble à ceci :

Résultat& = NomApi& ([ Liste d'arguments]

1. Le plus souvent, la valeur de retour d'une fonction est le code de sortie de l'opération. De plus, une valeur non nulle dans ce cas signifie un achèvement normal, zéro - une erreur. Vous pouvez généralement (mais pas toujours) vérifier la nature de l'erreur en appelant la fonction GetLastError. La description de cette fonction est la suivante : Declare Function GetLastError& Lib "kernel32" ()

   ATTENTION! Lorsque vous travaillez dans VB, il est préférable d'utiliser la propriété LastDLLError de l'objet Err pour obtenir la valeur du code d'erreur raffiné, car VB réinitialise parfois la fonction GetLastError entre l'appel de l'API et la poursuite de l'exécution du programme.

   Vous pouvez interpréter le code renvoyé par GelLastError à l'aide des constantes écrites dans le fichier API32.TXT, dont les noms commencent par le suffixe ERROR_.

   Plus erreurs typiques avoir les codes suivants :

   • ERROR_INVALID_HANDLE = 6& - identifiant invalide
   • ERROR_CALL_NOT_IMPLEMENTED = 120& - appel sous Windows 9x une fonction disponible uniquement pour Windows NT
   • ERROR_INVALID_PARAMETER = 87& - valeur de paramètre invalide

   Cependant, de nombreuses fonctions renvoient la valeur d'un paramètre demandé (par exemple, OpenFile renvoie la valeur d'un descripteur de fichier). Dans de tels cas, l'erreur est définie par une autre valeur Return& spéciale, le plus souvent 0 ou -1.

2. Les API Win32 utilisent des méthodes strictement fixes pour transmettre les types de données les plus simples. a) ByVal ... As Long

   Les variables longues gèrent au moins 80 % des arguments passés. Notez que l'argument toujours est suivi du mot-clé ByVal, ce qui signifie, entre autres, qu'un transfert de données unidirectionnel est effectué - du programme VB à la fonction API.

   B) ByVal ... As String

   Ce type de transfert de données est également assez courant, et avec un argument également toujours ByVal est appliqué. Lorsqu'une fonction API est appelée, l'adresse de la chaîne est écrite sur la pile, donc dans ce cas, un échange de données bidirectionnel est possible. Il existe plusieurs dangers dont il faut être conscient lorsque l'on travaille avec des chaînes.

   La première est que la mémoire est réservée pour une chaîne dans le programme appelant, donc si la fonction API remplit des chaînes, alors avant de l'appeler, vous devez créer une chaîne de la taille requise. Par exemple, la fonction GetWindowsDirectory renvoie le chemin d'accès au répertoire Windows, qui par définition ne doit pas dépasser 144 caractères. En conséquence, l'appel à cette fonction devrait ressembler à ceci :

   WinPath$ = Space$(144) ‘chaîne réservée en _ 144 caractères Result& = GetWindowsDirectory& (WinTath$, 144) _ ‘buffer fill’ Result& - nombre réel de caractères dans le nom du répertoire _ WinPath$ = Left$(WinPath, Result&)

   Le deuxième problème est que lorsque la fonction API est appelée, la chaîne source est convertie en une représentation interne de celle-ci, et vice versa lorsque la fonction se termine. Si à l'époque de Win16 cette opération consistait uniquement à ajouter un octet nul à la fin de la chaîne, alors avec l'avènement de Win32, la transformation du codage à deux octets Unicode en ANSI et vice versa s'y est ajoutée. (Ceci a été discuté en détail dans l'article "Features of Working with String Variables in VB", ComputerPress 10'99 et 01'2000). Pour l'instant, notez simplement qu'en utilisant la construction ByVal ... As String, vous ne pouvez échanger que des chaînes avec des données de type caractère.

   C) ... comme tout

   Cela signifie qu'une adresse de tampon mémoire sera poussée sur la pile, dont le contenu sera interprété par la fonction API, par exemple, en fonction de la valeur d'autres arguments. Cependant, As Any ne peut être utilisé que dans une instruction Declare - une variable spécifique doit être définie comme argument lorsqu'un appel spécifique à la fonction est effectué.

   D) ... En tant que type défini par l'utilisateur

   Une telle construction est également souvent utilisée lorsqu'il est nécessaire d'échanger des données (généralement dans les deux sens) en utilisant une certaine structure. Cette construction est en fait une sorte d'implémentation concrète du formulaire de transfert As Any, c'est juste que dans ce cas, la fonction est définie sur une structure fixe.

   La forme de la structure de données est définie par une fonction API particulière, et il est de la responsabilité du programmeur de la décrire correctement et de la réserver dans le programme appelant. Une telle conception toujours utilisé sans pour autant mots ByVal, c'est-à-dire, dans ce cas, le passage par référence est effectué - l'adresse de la variable est écrite dans la pile.

Un exemple d'appel d'une fonction API

Illustrons ce qui précède avec un exemple d'utilisation de deux fonctions de fichier utiles - lopen et lread , qui sont décrites comme suit :

Déclarez la fonction lread Lib "kernel32" _ Alias ​​"_lread" (_ ByVal lpFileName As String, _ ByVal wReadWrite As Long) Déclarez la fonction lread Lib "kernel32" _ Alias ​​"_lread" (_ ByVal hFile As Long, lpBuffer As Any, _ ByVal wBytes As Long) As Long

En VB, leurs homologues - dans ce cas, les exacts - sont les opérateurs Open et Get (pour le mode binaire). Faisons immédiatement attention à l'utilisation du mot-clé Alias ​​​​dans la déclaration de fonction - c'est juste le cas lorsque vous ne pouvez pas vous en passer. Les vrais noms de fonction dans la bibliothèque commencent par un trait de soulignement (style C typique), ce qui n'est pas autorisé dans VB.

L'opération d'ouverture de fichier peut ressembler à ceci :

Const INVALID_HANDLE_VALUE = -1 ' invalid _ handle value lpFileName$ = “D:\calc.bas” ' file name wReadWrite& = 2 ' read-write mode hFile& = lopen(lpFileName$, wReadWrite&) _ ' definit file handle If hFile& = INVALID_HANDLE_VALUE Alors _ ' erreur d'ouverture de fichier ' Spécifier le code d'erreur CodeError& = Err.LastDllError 'CodeError& = GetLastError _ ' cette construction ne fonctionne pas End If

Ici, vous devez faire attention à deux points:

• comme valeur de la fonction, nous obtenons la valeur du descripteur de fichier. Une erreur correspond à une valeur de -1 ;
• juste dans ce cas, l'appel à la fonction GetLastError ne fonctionne pas - pour obtenir la valeur d'erreur raffinée, nous nous sommes tournés vers l'objet Err (nous avons parlé de la possibilité d'une telle situation ci-dessus).

Vous pouvez ensuite lire le contenu du fichier, mais cela suppose que le programmeur doit avoir une certaine compréhension de sa structure (tout comme cela se produit lorsque vous travaillez avec des fichiers binaires arbitraires). Dans ce cas, l'appel à la fonction lread pourrait ressembler à ceci :

Dim MyVar As Single wBytes = lread (hFile&, MyVar, Len(MyVar) ‘ read nombre réel, 4 octets ' wBytes - nombre de données effectivement lues, ' -1 - erreur... Type MyStruct x As Single i As Integer End Type Dim MyVar As MyStruct wBytes = lread (hFile&, MyVar, Len(MyVar)) ' read data structure , 6 octets

Notez à nouveau que le deuxième argument de la fonction est passé par référence, le reste par valeur.

Dim MyVar As String MyVar = Space$(10) 'variable de réserve pour 10 caractères wBytes = lread (hFile&, ByVal MyVar, Len(MyVar)) ' lecture d'une chaîne de caractères, 10 caractères

Ici, vous pouvez voir une différence importante par rapport à l'exemple précédent - une variable de chaîne est nécessairement accompagnée du mot-clé ByVal.

La lecture du contenu d'un fichier dans un tableau (pour simplifier, nous utiliserons un tableau d'octets à une dimension) s'effectue de la manière suivante :

Dim MyArray(1 To 10) As Byte wBytes = lread (hFile&, MyArray(1), _ Len(MyArray(1))* 10) ‘ lecture de 10 éléments de tableau

En spécifiant le premier élément du tableau en argument, on passe l'adresse du début de la zone mémoire réservée au tableau. Évidemment, n'importe quel fragment du tableau peut être rempli de cette façon :

WBytes = lread (hFile&, MyArray(4), _ Len(MyArray(1))* 5) ' lit les éléments du tableau du 4ème au 8ème

Astuce 5 : Utilisez un alias pour les transmissions et paramètres comme n'importe lequel

Ici, sur la base de l'exemple précédent, nous allons révéler l'essence du quatrième conseil de Dan Appleman.

Lorsque vous travaillez avec la fonction lread, vous devez vous rappeler que lorsque vous y accédez à l'aide d'une variable de chaîne, vous devez utiliser le mot-clé ByVal (sinon le message concernant une opération illégale ne peut être évité). Pour être sûr, vous pouvez faire une description spéciale supplémentaire de la même fonction pour ne fonctionner qu'avec des variables de chaîne :

Déclarer la fonction lreadString Lib "kernel32" _ Alias ​​​​"_lread" (_ ByVal hFile As Long, ByVal lpBuffer As String, _ ByVal wBytes As Long) As Long

Lorsque vous travaillez avec cette description, vous n'avez plus besoin de spécifier ByVal lors de l'accès :

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

Il semblerait que la syntaxe de l'opérateur Declare vous permette de faire une telle déclaration spéciale pour un tableau :

Déclarer la fonction lreadString Lib "kernel32" Alias ​​"_lread" (_ ByVal hFile As Long, lpBuffer() As Byte, _ ByVal wBytes As Long) As Long

Cependant, l'appel

WBytes = lreadArray(hFichier&, MonTableau(), 10)

conduit inévitablement à une erreur de programme fatale.

Ceci est la suite de la conversation sur les particularités du traitement des variables de chaîne en Visual Basic : VB utilise un encodage Unicode à deux octets, Win API utilise un encodage ANSI à un octet (de plus, avec le format adopté en C, avec un octet nul à la fin). Par conséquent, lors de l'utilisation de variables de chaîne comme argument, la conversion d'Unicode en ANSI est toujours effectuée automatiquement lors de l'appel d'une fonction API (plus précisément, une fonction DLL) et inversement lors du retour.

Le résultat est simple : les variables de chaîne peuvent être utilisées pour échanger des données de caractères, mais elles ne peuvent pas être utilisées pour échanger des informations binaires arbitraires (comme c'était le cas avec les versions 16 bits de VB). Dans ce dernier cas, il est préférable d'utiliser un tableau d'octets à une dimension.

Comme vous le savez, le type String peut être utilisé pour décrire une structure personnalisée. A cet égard, il convient de rappeler ce qui suit :

• Il est strictement interdit d'utiliser la construction suivante pour accéder à l'API Win : Type MyStruct x As Single s As String ‘ chaîne de longueur variable End Type

  Dans le cas d'une chaîne de longueur variable, un descripteur de chaîne est passé dans le cadre de la structure, avec toutes les conséquences qui en découlent sous la forme d'une erreur d'exécution du programme.

• Vous pouvez utiliser une chaîne de longueur fixe comme élément de structure : Type MyStruct x As Single s As String*8 ‘ chaîne de longueur fixe End Type

Dans ce cas, la conversion de codage correspondante est effectuée.

Et la dernière note : vous ne pouvez en aucun cas utiliser un tableau de variables de chaîne (à la fois de longueur fixe et variable) lors de l'accès à une fonction API. Sinon, l'émergence d'une "opération illégale" sera garantie.

Il est probable que vous vous trouviez dans une situation où vous deviez écrire vos propres fonctions DLL. Cela sera inévitablement nécessaire si vous utilisez la technologie de la programmation mixte - l'utilisation de deux langages de programmation ou plus pour implémenter une application.

A ce propos, on note que la programmation mixte est assez courante pour la mise en place d'une application assez complexe. En effet, chaque langage (plus précisément, un système de programmation basé sur un langage) a ses propres forces et faiblesses, il est donc tout à fait logique d'utiliser les avantages de différents outils pour résoudre différents problèmes. Par exemple, VB - pour créer une interface utilisateur, C - pour un accès efficace aux ressources système, Fortran - pour la mise en œuvre d'algorithmes numériques.

L'avis de l'auteur est le suivant : toute programmation sérieuse nécessite que le développeur possède au moins deux outils. Bien sûr, dans les conditions actuelles d'une division claire du travail, il est très difficile d'être un excellent expert même dans deux systèmes, donc le schéma «langues principales et auxiliaires» est plus logique. L'idée ici est que même une connaissance sommaire de la langue "auxiliaire" (écriture de procédures assez simples) peut grandement améliorer l'efficacité de la langue "principale". Notez que la connaissance de VB, au moins en tant qu'auxiliaire, est aujourd'hui une exigence presque obligatoire pour un programmeur professionnel. Soit dit en passant, à l'époque du DOS pour tout programmeur, y compris Basic, il était hautement souhaitable de connaître les bases de l'assembleur.

D'une manière ou d'une autre, mais même dans les conditions de travail de groupe, lorsque chaque programmeur est engagé dans sa propre activité spécifique, tous les participants au projet doivent avoir une idée des fonctionnalités de l'interface procédurale dans différentes langues. Et de savoir que de nombreux systèmes de programmation (dont VB), en plus de l'interface par défaut, permettent d'utiliser d'autres méthodes étendues d'appel de procédures, qui permettent d'adapter l'interface à un autre langage.

Lors de l'étude de l'interface interprocédurale, vous devez faire attention aux "pièges" possibles suivants :

• Différentes langues peuvent utiliser différentes conventions pour écrire les identifiants. Par exemple, il est courant d'utiliser un trait de soulignement au début d'un nom de procédure, ce qui n'est pas autorisé en VB. Ce problème est facilement résolu en utilisant le mot-clé Alias ​​​​dans l'instruction Declare (voir Astuce 2-3 par exemple).
• Une séquence différente d'écriture des arguments transmis à la pile peut être utilisée. Par exemple, à l'époque de DOS (pour être honnête - je ne sais pas à quoi ça ressemble maintenant dans un environnement Windows), C écrivait des arguments à partir de la fin de la liste, d'autres langages ​​​​(Fortran, Pascal, Basic ) - Depuis le début.
• Par défaut sont utilisés différents principes passer des paramètres - par référence ou par valeur.
• Divers principes de stockage des variables de chaîne. Par exemple, en C (ainsi qu'en Fortran et Pascal), la longueur d'une chaîne est déterminée par un octet nul à la fin de celle-ci, tandis qu'en Basic, la longueur est écrite explicitement dans le descripteur de chaîne. Bien sûr, vous devez garder à l'esprit la possibilité d'utiliser différents encodages de caractères.
• Lors du transfert de tableaux multidimensionnels, il convient de rappeler qu'il existe différentes options pour convertir des structures multidimensionnelles en structures unidimensionnelles (à partir du premier index ou du dernier, par rapport aux tableaux bidimensionnels - "par lignes" ou "par colonnes ”).

Dans cette optique, les recommandations suivantes peuvent être faites :

• Utilisez les méthodes éprouvées les plus simples pour transmettre des arguments aux fonctions DLL. Les normes adoptées pour l'API Win conviennent tout à fait comme modèle.
• Ne transmettez jamais de tableaux de variables de chaîne.
• Soyez très prudent lorsque vous passez des variables de chaîne simples et des tableaux multidimensionnels.
• Assurez-vous de vérifier la fonctionnalité du mécanisme de transmission d'arguments vers et depuis la procédure appelée d'une manière spéciale. Écrivez un test personnalisé pour vérifier le transfert de données. Vérifiez séparément que chaque argument est passé correctement. Par exemple, si vous avez une procédure avec plusieurs arguments, vérifiez d'abord l'exactitude de la transmission de chaque paramètre pour une variante avec un argument, puis seulement - pour toute la liste.

Mais que se passe-t-il si la fonction DLL est déjà écrite, par exemple, en Fortran, mais que son interface d'entrée ne correspond pas très bien aux normes VB ci-dessus ? Il y a deux conseils ici. Tout d'abord : écrivez une fonction DLL de test et utilisez-la pour essayer de trouver le bon appel à partir du programme VB par essais et erreurs. Deuxièmement : écrivez une procédure d'adaptation dans le même Fortran qui fournirait une interface simple entre VB et une fonction DLL avec la transformation de structures de données simples en structures complexes (par exemple, la conversion d'un tableau d'octets multidimensionnel en un tableau de chaînes).

Donc : utilisez les fonctions DLL. Mais restez vigilant...

OrdinateurPresse 9" 2000

Les API peuvent être à la fois amusantes et frustrantes. D'une part, en interagissant avec d'autres applications, vous pouvez augmenter considérablement la portée de l'audience et "l'effet wow" de votre application. D'autre part, cela inclut la lecture de tonnes de documentation, l'apprentissage des stratégies d'authentification et l'analyse des messages d'erreur non informatifs (ou même manquants).

Tout d'abord, si vous ne comprenez toujours pas ce qu'est une API (Application Programming Interface), lisez l'explication de Skillcrush puis la première partie de cet article pour vous rattraper.

"API" est un concept incroyablement large - chaque fois que votre application "parle" à une autre application, c'est via une sorte d'API. Les composants de votre propre application, comme les différentes parties de Rails, communiquent également entre eux via une API. Ce sont des sous-applications plus ou moins indépendantes qui transmettent les données dont chacune a besoin pour effectuer ses propres tâches spécifiques. Dans le monde des applications, tout est une API !

Lorsque vous créez des applications avec des fonctionnalités frontales plus dynamiques (à la fois des applications Javascript d'une seule page et des applications simples avec des appels AJAX séparés), elles communiqueront avec le backend Rails via votre propre API, qui n'est en réalité qu'une ligne ou deux de code supplémentaire. . , indiquant à vos contrôleurs comment servir JSON ou XML au lieu de HTML.

Dans ce tutoriel, vous apprendrez à créer votre propre API. Dans les leçons suivantes, nous verrons comment interagir avec les API d'autres applications. Les leçons devraient être un bon tremplin pour apprendre sur ce sujet, mais il est peu probable qu'elles puissent couvrir entièrement tous les cas. Une grande partie du travail avec les API consiste à pouvoir lire leur documentation et à comprendre ce qu'ils attendent de vous.

Points de réflexion

Passez en revue les questions et voyez si vous connaissez les réponses. Vérifiez-vous à nouveau après avoir terminé la tâche.

• Comment Rails comprend le type de fichier que vous attendez en réponse lorsque vous envoyez une requête HTTP.
• A quoi sert la méthode #respond_to ?
• Comment renvoyez-vous un objet utilisateur (User) tout en spécifiant des attributs que vous ne voulez pas inclure dans cet objet (c'est-à-dire que vous ne pouvez pas simplement renvoyer User.first) ?
• Nommez 2 étapes dans les coulisses de la méthode #to_json.
• Comment dire à une action du contrôleur de n'afficher qu'un message d'erreur ?
• Comment créer votre propre message d'erreur ?
• Pourquoi ne pouvez-vous pas utiliser les méthodes d'authentification du contrôleur basées sur la session si vous souhaitez autoriser la connexion par programmation à votre API ?
• Qu'est-ce que "l'Architecture Orientée Services" ?

Principes de base de l'API

Votre application Rails est en fait déjà une API, même si vous ne la considérez peut-être pas comme une API. Le navigateur Web lancé par vos utilisateurs est également un programme. Il envoie donc une requête API à votre application Rails lorsque l'utilisateur ouvre une nouvelle page. Nous avons tendance à penser de cette façon parce que le rendu des modèles HTML est une tâche si courante que nous nous contentons de coder en dur cette fonctionnalité dans nos programmes serveur en tant que type de réponse standard, et considérons tout le reste comme quelque chose d'inhabituel.

Cependant, vous souhaitez souvent faire une demande qui ne vous oblige pas à passer par tous les maux de tête liés à l'utilisation d'un navigateur. Vous ne vous souciez peut-être pas de la structure de la page (HTML), mais en retour vous voulez des données propres. Supposons que vous souhaitiez obtenir une liste de tous les utilisateurs. Vous pouvez demander quelque chose comme http://yourapplication.com/users , qui déclenchera probablement l'action #index et affichera une liste de tous les utilisateurs de l'application.

Mais pourquoi s'embêter avec toutes ces informations supplémentaires alors que tout ce que vous voulez, c'est une liste d'utilisateurs ? L'option la plus simple serait d'envoyer une requête à la même URL, en spécifiant l'attente d'une réponse JSON ou XML en retour. Si vous configurez correctement votre contrôleur Rails, vous obtiendrez un simple objet tableau JSON contenant tous les utilisateurs. Formidable!

Le même principe s'applique lorsque vous communiquez avec une API externe. Supposons que vous souhaitiez obtenir les "tweets" récents d'un utilisateur sur Twitter. Tout ce que vous avez à faire est de dire à votre application Rails comment interagir avec l'API Twitter (c'est-à-dire vous authentifier), soumettre la demande et traiter l'ensemble de "tweets" qui sera renvoyé.

Création d'une API

Vous voudrez peut-être faire de votre application Rails une pure API back-end pour les pages Web front-end, ou vous voudrez peut-être simplement apprendre à envoyer du JSON lorsque le front-end le demande. Cette section ne couvrira pas la création d'API RESTful à part entière avec la fonctionnalité d'authentification. Il s'agit d'une introduction en douceur au traitement de votre application comme une API.

Bases

Si vous voulez que votre application Rails renvoie JSON au lieu de HTML, vous devrez dire à votre contrôleur de le faire. La grande chose est que la même action de contrôleur peut retourner différents types selon que votre utilisateur effectue une requête de navigateur normale ou accède à l'API via la ligne de commande. Cela détermine le type de demande qui a été effectué en fonction de l'extension du fichier demandé, tel que example.xml ou example.json .

Vous pouvez vérifier ce que Rails "pense" du type de fichier que vous attendez en consultant le journal du serveur :

Démarrage de GET "/posts/new" pour 127.0.0.1 au 2013-12-02 15:21:08 -0800 Traitement par PostsController#new en tant que HTML

La première ligne vous indique quelle URL a été demandée, et la seconde vous indique où elle a été dirigée et comment Rails la gère. Si vous deviez utiliser l'extension .json, cela ressemblerait à ceci :

Démarrage de GET "/posts.json" pour 127.0.0.1 au 2013-12-04 12:02:01 -0800 Traitement par PostsController#index en tant que JSON

Si vous avez une application de test en cours d'exécution, essayez de demander différentes URL. Si votre contrôleur ne sait pas comment les gérer, vous risquez d'obtenir une erreur, mais vous devriez toujours pouvoir voir ce que Rails comprend par vos requêtes.

Rendu JSON ou XML

Lorsque vous décidez de répondre avec JSON ou XML, vous devrez indiquer à votre contrôleur de rendre JSON ou XML au lieu de HTML. Une façon de le faire est d'utiliser la méthode #respond_to :

Utilisateurs de classeContrôleur< 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

Dans ce cas, #respond_to transmet un objet de format au bloc auquel vous pouvez attacher l'appel de rendu approprié. Si vous ne faites rien, le html sera rendu à l'aide du modèle Rails standard (app/views/index.html.erb dans cet exemple).

La fonction #render est suffisamment intelligente pour comprendre comment rendre une grande variété de formats. Lorsque vous lui passez la clé:json , il appellera #to_json sur la valeur dans cet exemple aux @utilisateurs. Cela convertira vos objets Ruby en chaînes JSON, qui seront transmises à l'application demandeuse.

C'est ainsi que vous obtenez votre API. Bien sûr, la création d'une API peut être un peu plus compliquée si vous voulez faire des trucs fantaisistes, mais c'est une question de base.

Spécification des attributs de retour

Supposons que vous vouliez vous assurer de ne pas renvoyer l'adresse e-mail d'un utilisateur avec un objet Utilisateur. Dans ce cas, vous voudrez changer les attributs qui seront retournés, en modifiant ce que fait la méthode #to_json.

Auparavant, vous auriez simplement remplacé la méthode #to_json par votre version, mais maintenant vous n'en avez plus besoin - en fait, vous remplacez la méthode #as_json à la place. La méthode #as_json est utilisée dans la méthode #to_json , donc la modifier modifie implicitement le résultat de #to_json , mais d'une manière assez spécifique.

#to_json fait 2 choses : exécute #as_json et obtient un hachage des attributs à rendre à JSON. Il rend ensuite au JSON en utilisant ActiveSupport::json.encode . Ainsi, en modifiant #as_json , vous êtes plus précis sur la partie de la méthode #to_json que vous souhaitez réellement modifier.

Dans notre cas, nous le faisons en modifiant #as_json dans notre modèle pour ne renvoyer que les attributs dont nous avons besoin :

# app/models/user.rb classe Utilisateur< ActiveRecord::Base # Вариант 1: Полное переопределение метода #as_json def as_json(options={}) { :name =>self.name ) # NE PAS inclure le champ de fin d'e-mail # Option 2 : Utiliser méthode standard#as_json def as_json(options=()) super(uniquement : [:nom]) fin fin

Ensuite, dans notre contrôleur, tout ce que nous avons à faire est de rendre le JSON comme d'habitude (l'exemple ci-dessous renverra toujours JSON, qu'une requête HTML ait été envoyée ou non) :

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

Notez que vous n'avez pas besoin d'appeler vous-même #to_json lorsque vous utilisez #render - il le fera pour vous.

Parfois, Heroku peut nécessiter des étapes supplémentaires pour afficher correctement vos pages d'erreur. Voir. Vous devrez peut-être d'abord supprimer les pages statiques du répertoire app/public.

Sécuriser de l'extérieur

Supposons que vous souhaitiez autoriser l'accès à l'API uniquement si l'utilisateur est connecté. L'authentification de votre contrôleur existant fait déjà le travail - assurez-vous simplement que vous avez le bon #before_action défini (par exemple, before_action:require_login). Vous voudrez peut-être une fonctionnalité où les utilisateurs connectés et non connectés peuvent afficher la page, mais chacun doit voir des données différentes. Vous ne voulez pas que les utilisateurs non connectés puissent faire des requêtes API pour récupérer des données sensibles. De même, vous ne voulez pas autoriser les utilisateurs non autorisés à visiter certaines pages HTML.

Si vous souhaitez traiter les requêtes d'une application qui n'est pas un navigateur (par exemple, de ligne de commande), vous ne pouvez pas compter sur les cookies du navigateur pour l'authentification. C'est pourquoi la plupart des API utilisent des jetons natifs dans le cadre du processus d'authentification. Nous parlerons un peu plus des jetons dans la prochaine leçon.

Prochaines étapes

Vous avez maintenant les compétences nécessaires pour utiliser votre application Rails pour servir non seulement HTML, mais tout autre format. Si vous voulez aller plus loin et laisser d'autres développeurs construire des choses en utilisant votre plate-forme (par exemple, afin qu'ils puissent faire des requêtes par programmation au lieu de s'authentifier en tant qu'utilisateur), vous devrez rendre votre système d'API beaucoup plus sécurisé. Nous ne couvrirons pas tout ici, mais consultez ce qui suit :

• L'article Building Awesome Rails APIs décrit plusieurs des meilleures approches pour passer d'une application jouet aux API standard de l'industrie.

Architecture orientée services

Il est temps d'introduire une approche architecturale appelée architecture orientée services (SOA). L'idée de base est que votre application sera composée de nombreux services, tels qu'un système de paiement, l'enregistrement des utilisateurs, un module de recommandation, etc. Au lieu de tout construire dans une seule application principale, vous décomposez les sous-systèmes en éléments complètement indépendants qui interagissent les uns avec les autres à l'aide d'API internes.

C'est bon pour de nombreuses raisons. En vous assurant que chaque élément de votre application ne se soucie pas du fonctionnement des autres parties et ne sait que demander des données via leur API, vous pouvez apporter des modifications importantes au code de service et le reste de l'application fonctionnera comme avant. Vous pouvez complètement remplacer un service par un autre, et tant qu'il communique en utilisant les mêmes méthodes API, tout se passera très bien. Vous pouvez utiliser des API externes dans le cadre de votre application (telles que des processeurs de paiement) au lieu d'écrire les vôtres. Vous pouvez créer une application PHP qui interagit avec une application Python qui interagit avec une application Rails, et tout fonctionnera, car ils communiquent entre eux à l'aide de l'API.

C'est généralement une bonne idée d'essayer de garder chaque partie de votre application aussi indépendante que possible. Le concept de SOA vous encourage à réfléchir exactement aux méthodes que vous souhaitez exposer à d'autres parties de votre application, et cela améliorera votre code en cours de route. De plus, en supposant que chaque composant majeur de votre application est indépendant, vous pouvez également isoler les problèmes beaucoup plus facilement et gérer les erreurs de manière plus intelligente.

Utiliser une architecture orientée services pour une application entière revient à décomposer un script Ruby géant et complexe en classes et méthodes astucieuses, mais à plus grande échelle.

Amazon.com est l'un des cas les plus célèbres de transition vers une architecture orientée services. Un jour de 2002, Jeff Bezos a déclaré sans ambages que toutes les équipes de travail devaient passer à la SOA sous peine d'être licenciées. Célèbre article de blog un employé de Google, destiné à des fins internes mais accidentellement exposé au public, a parlé de la puissance d'Amazon utilisant SOA. C'est une excellente lecture, alors assurez-vous de la noter, mais les principales thèses de la lettre de Bezos sont extraites des citations suivantes du message :

1) Toutes les commandes fournissent désormais leurs données et fonctionnalités via des interfaces de service.

2) Les équipes doivent communiquer entre elles via ces interfaces.

3) Les autres formes de communication inter-processus sont interdites : pas de liens directs, pas de lecture directe de données d'une autre commande, pas de modèles de mémoire partagée, pas de "portes dérobées", etc. La seule façon autorisée de communiquer est d'accéder à l'interface de service sur le réseau.

4) Peu importe la technologie qu'ils utilisent. HTTP, Corba, Pubsub, protocoles natifs - peu importe. Bezos s'en fiche.

5) Toutes les interfaces de service, sans exception, doivent être initialement conçues avec la possibilité d'être contrôlées de l'extérieur. Autrement dit, l'équipe doit planifier et concevoir pour être en mesure de fournir une interface aux développeurs extérieurs à l'entreprise. Aucune exception.

6) Toute personne ignorant ces exigences sera renvoyée.

La SOA est une affaire sérieuse. Bien sûr, il y a beaucoup de problèmes qui surviennent lors de son utilisation - consultez ce post sur les "leçons apprises" d'Amazon - mais il a une quantité incroyable d'avantages.

Vous ne vous soucierez probablement pas trop de SOA pendant que vous créez des applications "jouets" pour vous-même, mais cette question se posera certainement lorsque vous commencerez à travailler pour une entreprise informatique, donc apprendre à la connaître est une bonne pratique.

Ton but

1. Lisez la section 7 du Rails Guide to Controllers pour en savoir plus sur le rendu JSON et XML.
2. Ils ne sont pas obligatoires (car ils vont un peu plus loin que ce que nous avons actuellement), mais si vous êtes intéressé, jetez un œil à Railscasts dans la section Ressources supplémentaires au bas du didacticiel pour en savoir plus sur les avantages du API.

Conclusion

Nous travaillerons plus étroitement avec votre application en tant qu'API pendant le cours Javascript. Dans ce cours, vous allez créer plusieurs applications full-stack qui utilisent des appels AJAX pour une meilleure expérience utilisateur, ce qui implique en fait le rendu de données XML ou JSON au lieu d'une page HTML complète. Ensuite, vous allez créer plusieurs applications Javascript d'une seule page qui s'appuient sur l'API fournie par votre application Rails pour obtenir toutes les données dont elles ont besoin à partir de la base de données, et sinon s'exécutent côté client (dans le navigateur).

La meilleure façon de gérer une API est de la créer et d'interagir avec elle, ce sur quoi nous nous concentrerons dans nos projets.