API dans le cloud (CAPI)

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 8 minutes de lecture

    • L'API dans le cloud (CAPI) vous permet d'intégrer Cloud Provisioning and Governance aux fournisseurs dans le cloud à l'aide des API REST.

    Composants CAPI

    L'intégration à des fournisseurs dans le cloud est effectuée via des appels REST, tels que PUT, GET, POST et DELETE. La CAPI fournit le cadre de travail permettant d'intégrer une API REST de fournisseurs dans le cloud afin que votre instance puisse communiquer avec le fournisseur dans le cloud et gérer les ressources dans le cloud.

    Consultez pour en savoir plus.

    La CAPI contient ces composants :
    Figure 1. Vue d'ensemble de CAPI
    Vue d'ensemble de CAPI
    Fournisseurs

    Les fournisseurs dans le cloud sont les clouds auxquels vous pouvez vous connecter. Par défaut, Cloud Provisioning and Governance inclut les fournisseurs les plus couramment utilisés, tels qu'AWS, Azure et VMware. Chaque fournisseur dispose de nombreux produits, chacun d'eux fournissant des types de ressources. Chaque type de ressource est mappé à un seul type de CI. Par exemple, le AWS provider inclut le produit AWS Elastic Compute Cloud, qui inclut le type de ressource AWS::EC2::Instance. Ce type de ressource est l'une des ressources dans le cloud les plus courantes que vous pouvez créer. Il est mappé directement au type de CI Instance d'ordinateur virtuel [cmdb_ci_vm_instance], où les ordinateurs virtuels sont enregistrés dans la CMDB.

    Interfaces

    Les interfaces définissent le cadre de travail selon lequel le système doit structurer les appels REST auxquels les API du fournisseur dans le cloud s'attendent. Les interfaces définissent les opérations, également appelées méthodes, et les paramètres dont chaque méthode a besoin.

    Les interfaces sont réutilisables. Si vous étendez la CAPI pour inclure de nouveaux produits et API, vous pouvez utiliser les interfaces existantes afin d'effectuer les mêmes appels REST.

    API

    Les API CAPI sont la composante principale d'une CAPI qui relie un produit et une interface. Les API incluent le code réel exécuté par le système.

    Chaque API CAPI inclut ces composants :
    • Les mappeurs de méthodes CAPI fournissent les méthodes mappées aux opérations définies dans l'interface. À partir des mappeurs de méthode CAPI, créez des script includes de Serveur MID dans JavaScript pour indiquer exactement au fournisseur dans le cloud ce qu'il faut faire. C'est par le biais des script includes que la connexion au fournisseur dans le cloud se produit.
      Remarque :
      Si vous créez des API CAPI personnalisées, le système fournit un script include vide que vous pouvez personnaliser. Vous pouvez également modifier les script includes existants sur les mappeurs de méthodes si nécessaire. Toutefois, bon nombre des API par défaut associées à l'application Cloud Provisioning and Governance n'utilisent pas de script includes modifiables. Les connexions sont codées en dur dans Java. Vous pouvez toujours utiliser ces API dans de nouveaux blocs de ressources que vous créez, mais vous ne pouvez pas modifier les API.
    • Les remplacements de configuration d'API contiennent l'identité, comme une clé et les informations d'identification, telles que la clé secrète, et d'autres paramètres importants requis par le fournisseur dans le cloud. Ces paramètres aident le fournisseur dans le cloud à effectuer les opérations dans la liste connexe Mappeurs de méthodes CAPI. Les remplacements de configuration d'API sont nécessaires, car lorsque le système appelle l'API du fournisseur dans le cloud via REST, les données d'informations d'identification ne sont pas incluses. Les blocs de ressources utilisent les paramètres et les valeurs que vous définissez dans les remplacements de configuration d'API pour interroger la banque d'identifiants. Lorsque votre API s'exécute, les attributs sont mis à la disposition de tous les appels de méthode dans votre script includes.

      Les remplacements sont inclus dans le périmètre uniquement pour cette API. Les remplacements ne remplacent rien dans les autres API.

    Puisque vous pouvez définir plusieurs versions d'une API CAPI avec de légères variations, vous pouvez étendre (sans remplacer) une API existante tout en conservant les fonctionnalités souhaitées.

    Cette image illustre les composants de CAPI utilisés lorsque vous mettez en service un ordinateur virtuel Azure à l'aide des paramètres CAPI par défaut fournis avec Cloud Provisioning and Governance :
    Figure 2. CAPI Azure
    CAPI Azure

    Dans cet exemple, le produit Microsoft.Compute est contenu dans le fournisseur Azure. Azure utilise le produit Microsoft.Compute pour les ordinateurs virtuels. Dans votre instance, le produit Microsoft.Compute est mappé au type de ressource Microsoft.Compute/virtualMachines, qui est associé au type de CI Virtual Machine Instance dans la CMDB.

    L'interface Compute contient des définitions pour des méthodes telles que CreateNode, qui définit la façon de créer l'ordinateur virtuel réel. Parmi les nombreux paramètres utilisés par CreateNode, Location capture le centre de données où se trouve l'ordinateur virtuel.

    Azure Compute API regroupe le produit Microsoft.Compute et la structure définies dans l'interface Compute. L'implémentation de la méthode CreateNode appelle le script include azure-compute-1.0-CreateNode Serveur MID, qui appelle le script include AzureComputeVirtualMachine Serveur MID. Les script includes effectuent les appels réels à l'API Azure. Pour accéder au compte Azure, les méthodes SecretKey, ClientID, TenantID et d'autres sont transmises dans les remplacements de configuration.

    Comment la CAPI s'intègre à l'instance

    La CAPI intègre ces composants à votre instance :
    Blocs de ressources Cloud Provisioning and Governance

    Un bloc de ressources représente une seule ressource dans le cloud, telle qu'un serveur virtuel, un stockage de serveur virtuel ou un centre de données. Vous pouvez également le considérer comme un type de CI dans la CMDB. Vous avez regroupé de nombreux blocs de ressources dans un plan, qui apparaît sous la forme d'un élément de catalogue (également appelé pile) pour vos utilisateurs dans le catalogue dans le cloud.

    Dans le système, chaque bloc de ressources est comme un conteneur qui fait référence à la CAPI et relie les réponses du fournisseur dans le cloud à un CI spécifique. Les blocs de ressources utilisent :
    • des étapes opérationnelles qui appellent la CAPI pour chaque opération, telles que l'opération de mise en service, et transmettent les valeurs de paramètres nécessaires au fournisseur dans le cloud pour exécuter l'opération ;
    • des processeurs de réponse qui traitent et analysent la réponse REST du fournisseur et mettent à jour les enregistrements dans la CMDB.
    La CMDB

    Chaque bloc de ressources est basé sur un type de CI de la CMDB. Pour Cloud Provisioning and Governance, tous les types de CI liés au cloud sont basés sur la classe Virtual Machine Object CI, qui fournit tous les attributs dont vous avez besoin pour toutes les ressources dans le cloud prises en charge par défaut. Si un type de CI pour une ressource dans le cloud n'existe pas dans le système de base, vous devez créer une nouvelle classe CI et ajouter les attributs nécessaires.

    Si vous créez une nouvelle classe CI, vous devez également créer :
    • une classe CI pour chacune des ressources disponibles pour vos utilisateurs. Toutes les classes CI sont basées sur la classe d'objets d'ordinateur virtuel.
    • Une règle d'identification qui spécifie un ID d'objet. Chaque fois que les composants de Gestion dans le cloud font référence à une ressource cloud spécifique dans la CMDB, ils ont besoin de l'ID d'objet pour trouver la ressource dans le cloud appropriée.
    • Une règle de relation qui spécifie comment la classe CI de la ressource est liée à d'autres classes CI. Par exemple, un CI virtual server doit avoir une relation Hosted on::Hosts avec un CI datacenter. Ces règles de relation sont nécessaires pour l'unicité du CI lorsqu'elles sont traitées par le moteur Identification et Réconciliation (IRE). La combinaison du compte de services, de l'ID d'objet de la ressource et du centre de données (ou emplacement) où se trouve la ressource détermine l'unicité.
    Script include de Serveur MID
    Chaque opération de l'API CAPI comporte un script include de Serveur MID que vous configurez. Le script include appelle les classes JavaScript qui sont déjà dans d'autres script includes dans le système, ou les classes JavaScript que vous créez. Finalement, la classe de l'appelant est appelée pour déclencher l'appel REST. Les script includes de Serveur MID sont configurés sur votre instance ServiceNow, mais s'exécutent sur le Serveur MID.

    Cette image illustre la façon dont les composants fonctionnent ensemble lorsqu'un utilisateur met en service une ressource à partir du portail de l'utilisateur dans le cloud :

    CAPI et votre instance

    Appels REST au fournisseur dans le cloud

    Les appels REST au fournisseur dans le cloud sont déclenchés à partir des script includes de Serveur MID qui sont référencés à partir des mappeurs de méthode CAPI scriptés à l'intérieur des enregistrements d'API CAPI. Pour créer vos propres API CAPI, ou pour créer des script includes de Serveur MID personnalisés (qui font partie des mappeurs de méthode CAPI), vous devez comprendre :
    Par exemple, pour apprendre à effectuer un appel REST vers Azure afin de créer un groupe de ressources, consultez cette rubrique Azure : Groupes de ressources : Créer ou mettre à jour. Vous pouvez trouver le point de terminaison, les paramètres et le corps de la demande dont Azure a besoin, ainsi que les réponses qu'il fournit. Vous pouvez voir que :
    • le point de terminaison est management.azure.com ;
    • la méthode à appeler avec une opération PUT est subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}?api-version=2018-02-01, où vous spécifiez l'ID d'abonnement, le nom du groupe de ressources et la version de l'API.

    N'oubliez pas que les appels d'API REST ont lieu à l'intérieur des script includes de Serveur MID qui sont associés aux mappeurs de méthode API CAPI. Appelez les méthodes que la CAPI met déjà à votre disposition à l'aide des classes étendues à partir de CloudAPIBase et CloudRESTAPIInvoker. Vous pouvez également créer d'autres script includes pour étendre ces classes de base et créer vos propres classes. Familiarisez-vous avec ces classes de base et les méthodes disponibles.

    Premiers pas

    1. Examiner les API CAPI fournies avec Cloud Provisioning and Governance par défaut.
    2. Passez en revue les classes CAPI fournies par défaut. Ces classes peuvent être appelées à partir des script includes de Serveur MID dans vos opérations API CAPI.
    3. Parcourez la mise en service d'un ordinateur virtuel Azure et d'un ordinateur virtuel AWS pour voir comment les composants fonctionnent ensemble. La procédure pas-à-pas Azure utilise un script include de Serveur MID afin que vous puissiez voir les différentes classes CAPI utilisées dans l'opération de mise en service. La procédure pas-à-pas AWS n'utilise pas de script include de Serveur MID.
    4. Ajouter un produit à un fournisseur existant dans la CAPI.
    5. Créer une classe CI pour une ressource dans le cloud virtuel.
    6. Créer ou étendre une interface CAPI.
    7. Créer une API CAPIet un script include de Serveur MID personnalisé qui effectue les appels REST au fournisseur dans le cloud. Un script include de Serveur MID vide est toujours généré pour les nouvelles API CAPI. Modifiez-la avec les appels à d'autres classes et méthodes JavaScript, telles que les méthodes de la classe Demandeur.