Ajouter une API en tant que fournisseur de type

Cette page explique comment ajouter une API à Deployment Manager en tant que fournisseur de type. Pour en savoir plus sur les types et les fournisseurs de types, lisez la documentation Présentation des types.

Un fournisseur de types expose toutes les ressources d'une API tierce à Deployment Manager en tant que types de base. Vous avez la possibilité de les utiliser dans vos configurations. Ces types doivent être directement diffusés par une API RESTful acceptant les opérations CRUD (création, lecture, mise à jour et suppression).

Vous pouvez ajouter n'importe quelle API en tant que fournisseur de types, sous réserve qu'elle dispose d'une spécification OpenAPI (anciennement connue sous le nom de Swagger©) ou d'un document Google Discovery. Ajoutez des fournisseurs de type pour utiliser des API qui ne sont pas fournies automatiquement par Google.

Ce document n'explique pas comment mettre en place votre propre service d'API. L'hypothèse de départ est la suivante : soit il existe déjà une API que vous voulez ajouter, soit vous avez déjà créé une API qui est en cours d'exécution et est accessible à partir d'un point de terminaison public. Vous pourriez ainsi déployer un exemple d'API à l'aide de Google Cloud Endpoints en suivant le tutoriel Démarrage rapide de Cloud Endpoints.

Avant de commencer

Composants d'un fournisseur de types

Un fournisseur de types est constitué des éléments suivants :

  • Un nom : le nom que vous souhaitez donner au fournisseur de types. Vous l'utiliserez pour référencer le type et les ressources d'API associées pertinentes.
  • Un document de descripteur : l'URL du document de descripteur du type. Les documents compatibles incluent les documents Google Discovery et les spécifications OpenAPI 1.2.
  • Une authentification : tous les identifiants d'authentification requis pour l'API. Vous pouvez spécifier une authentification de base. Si votre API est exécutée sur Google Endpoints ou Google Kubernetes Engine, vous pouvez utiliser les identifiants du compte de service du projet pour vous authentifier.
  • Des options avancées : les options d'API et mappages d'entrée avancés.

Nom

Il s'agit du nom du fournisseur de types. Vous devrez l'utiliser pour faire référence au type dans vos futurs modèles et configurations. Par exemple, si vous créez un fournisseur de types et que vous le nommez my-awesome-type-provider, vous devrez l'utiliser dans vos modèles ultérieurs comme suit :

resources:
  name: a-deployment
  type: my-project/my-awesome-type-provider:some-collection
  properties:
  …

my-project est l'ID du projet auquel appartient le type et some-collection est le chemin d'accès à la ressource d'API que vous créez.

Document de descripteur

Le document de descripteur d'un fournisseur de types peut être une spécification OpenAPI 1.2 ou 2.0, ou un document Google Discovery. Vous pouvez par exemple trouver le document Google Discovery associé à l'API bêta de Compute Engine à cette adresse :

https://content.googleapis.com/discovery/v1/apis/compute/beta/rest

Consultez la liste complète des documents Google Discovery.

Les documents OpenAPI 1.2 et OpenAPI 2.0 sont également acceptés.

Authentification

Si votre API nécessite une authentification, vous pouvez fournir les informations ici. Deployment Manager accepte les identifiants d'authentification de base tels que les noms d'utilisateurs et les mots de passe. Pour Google Kubernetes Engine et Google Cloud Endpoints, vous pouvez utiliser l'en-tête Authorization pour fournir un jeton d'accès depuis le compte de service du projet.

Pour spécifier l'authentification de base, indiquez le nom d'utilisateur et le mot de passe dans la section credentials :

credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

Vous devez spécifier le nom d'utilisateur et le mot de passe uniquement la première fois que vous créez un fournisseur de types.

Si vous disposez d'un cluster qui s'exécute sur Google Kubernetes Engine, vous pouvez l'ajouter en tant que fournisseur de types et accéder à l'API Kubernetes à l'aide de Deployment Manager. Cela suppose que le cluster soit exécuté dans le projet où vous utilisez Deployment Manager. Dans ce scénario, vous pouvez obtenir le jeton d'accès OAuth 2.0 du compte de service des API Google du projet et l'indiquer dans l'en-tête Authorization. Contrairement à la section ci-dessus traitant des identifiants, vous devez fournir le mappage d'entrée suivant dans votre requête :

- fieldName: Authorization
  location: HEADER
  value: >
    $.concat("Bearer ", $.googleOauth2AccessToken())

La méthode googleOauth2AccessToken() obtient automatiquement un jeton d'accès lorsque l'utilisateur appelle ce fournisseur de types. Pour un exemple complet, reportez-vous à la section Exemple de type et cluster GKE.

Vous pouvez utiliser la même méthode pour vous authentifier auprès de Google Cloud Endpoints.

Options de type avancées

Certaines API peuvent présenter des particularités qui rendent très difficile le mappage automatisé de toutes leurs propriétés par Deployment Manager. Dans un scénario idéal, vous fournissez un document de descripteur et Deployment Manager s'occupe de déterminer automatiquement les chemins de requête d'API et les propriétés d'API pertinentes sans travail supplémentaire de votre part. En ce qui concerne les API plus complexes, Deployment Manager sera sans aucun doute en mesure de comprendre la majorité de l'API, mais il sera peut-être nécessaire de spécifier explicitement les mappages d'entrée pour les comportements de l'API les moins évidents.

Pour en savoir plus sur les mappages d'entrée, lisez la documentation relative aux options d'API avancées.

Création d'un fournisseur de types

Pour créer un fournisseur de types, envoyez une requête à Deployment Manager. La charge utile de la requête doit contenir le nom du fournisseur de types souhaité, l'URL du document de descripteur et toutes les informations d'authentification requises.

gcloud

Pour créer un fournisseur de types à l'aide de l'outil gcloud, utilisez la commande type-providers create :

gcloud beta deployment-manager type-providers create [TYPE_PROVIDER_NAME] --descriptor-url=[URL]

où :

  • [TYPE_PROVIDER_NAME] est le nom que vous souhaitez donner à ce type.
  • [URL] est l'URL complète du document de descripteur prenant en charge ce type. Exemple :

    http://petstore.swagger.io/v2/swagger.json
    

Si vous souhaitez fournir des identifiants d'authentification ou des options d'API avancées, vous pouvez créer un fichier d'options d'API écrit en YAML et le spécifier via l'indicateur --api-options-file. Ce fichier pourrait par exemple ressembler à ceci :

collectionOverrides:
- collection: /emailAddresses/v1beta/people
  options:
    inputMappings:
    - methodMatch: ^create$
      fieldName: emailAddress.displayName
      value: $.resource.properties.displayName
      location: BODY
    - methodMatch: ^update$
      fieldName: displayName
      value: $.resource.properties.displayName
      location: PATH
    virtualProperties: |
      schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        displayName:
          type: string
      required:
      - displayName
credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

La commande gcloud correspondante serait la suivante :

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url]

API

Pour créer un type de base dans l'API, effectuez une requête POST. Le corps de cette requête doit contenir la valeur descriptorUrl et éventuellement des options de configuration. Exemple :

POST https://www.googleapis.com/deploymentmanager/v2beta/projects/[PROJECT_ID]/global/typeProviders

{ "description":"",
  "descriptorUrl":"https://www.example.com/api/v1beta1.json",
  "name":"my-type-provider",
  "collectionOverrides":[
    {
      "collection":"emailAddresses/v1beta/people",
      "options":{
        "inputMappings":[
          {
            "fieldName":"emailAddress.displayName",
            "location":"BODY",
            "methodMatch":"^create$",
            "value":"$.resource.properties.displayName"
          },
          {
            "fieldName":"displayName",
            "location":"PATH",
            "methodMatch":"^update$",
            "value":"$.resource.properties.displayName"
          }
        ],
        "virtualProperties":"schema: http://json-schema.org/draft-04/schema#\ntype: object\nproperties:\n  displayName:\n    type: string\nrequired:\n- displayName\n"
      }
    }
  ],
  "credential":{
    "basicAuth":{
      "password":"example-password",
      "user":"example-user"
    }
  }
}

Pour en savoir plus, consultez la documentation de la méthode insert.

Tester votre fournisseur de types

Pour vérifier que votre fournisseur de types fonctionne comme prévu :

  1. Appelez votre nouveau fournisseur de type dans une configuration.
  2. Déployez chaque collection proposée par le fournisseur de types pour vous assurer que l'API fonctionne comme prévu. Une collection est une ressource d'API du fournisseur de type spécifié.
  3. Effectuez la mise à jour de chaque collection.
  4. Supprimez chaque collection.

Lorsqu'un utilisateur instancie un type à partir de votre fournisseur de types, il envoie une requête à Deployment Manager, mais pas explicitement à l'API sous-jacente. Deployment Manager construit ensuite la requête avec les informations fournies pour envoyer une demande à l'API au nom de l'utilisateur. Le fait qu'une API soit dotée de propriétés difficilement identifiables par Deployment Manager est le problème le plus fréquemment observé. Par exemple, certaines API requièrent des propriétés qui peuvent uniquement être extraites à partir d'une réponse d'API. D'autres API peuvent utiliser le même nom de champ avec des valeurs différentes en fonction de l'opération. Vous devez indiquer explicitement à Deployment Manager comment gérer ces scénarios.

Si votre API présente l'une de ces caractéristiques, utilisez des mappages d'entrée afin de lever toute ambiguïté pour Deployment Manager.

Étapes suivantes

© 2016 Swagger. Tous droits réservés.

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Documentation Cloud Deployment Manager