Ajouter une API en tant que fournisseur de types

Cette page explique comment ajouter une API à Google Cloud Deployment Manager en tant que fournisseur de types. 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 que vous pouvez 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).

Si vous souhaitez utiliser une API qui n'est pas automatiquement fournie par Google avec Deployment Manager, vous devez l'ajouter en tant que fournisseur de types. 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.

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. Par exemple, pour déployer un exemple d'API à l'aide de Google Cloud Endpoints, vous pouvez suivre le guide de démarrage rapide de Cloud Endpoints.

Avant de commencer

Si vous voulez vous servir des exemples de ligne de commande de ce guide, installez l'outil de ligne de commande gcloud.
Si vous voulez utiliser les exemples d'API de ce guide, configurez l'accès aux API.
Configurez l'accès à l'API v2beta si vous souhaitez utiliser les exemples d'API de ce guide.

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.
Authentification : tous identifiants d'authentification requis pour l'API. Vous pouvez spécifier l'authentification de base. Si votre API est exécutée sur Cloud Endpoints ou Google Kubernetes Engine (GKE), vous pouvez également utiliser les identifiants du compte de service du projet pour vous authentifier.
Des options avancées : les options d'API ou mappages d'entrée avancés de votre choix.

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:
  …

Où 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, telles 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 les identifiants d'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 (GKE) dans le projet où vous utilisez Deployment Manager, vous pouvez l'ajouter en tant que fournisseur de types et utiliser Deployment Manager pour accéder à l'API GKE. 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 précédente concernant les 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.

Autorité de certification racine personnalisée (facultatif)

Si vous souhaitez ajouter à l'API Deployment Manager une API en tant que fournisseur de types et que le point de terminaison HTTPS de cette API utilise un certificat qui n'est pas fourni par une autorité de certification publiquement approuvée pour chiffrer la connexion, vous pouvez l'ajouter à votre configuration comme décrit dans l'exemple suivant :

customCertificateAuthorityRoots:
- $(ref.my-gke-cluster.masterAuth.clusterCaCertificate)

où my-gke-cluster est le cluster GKE que vous utilisez. Pour obtenir un exemple détaillé, reportez-vous à la section Exemple de cluster de fournisseur GKE.

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 gcloud CLI, exécutez 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 à l'aide de l'option --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]

Si vous souhaitez vous authentifier à l'aide d'une autorité de certification personnalisée, vous pouvez ajouter celle-ci en tant qu'option à la commande gcloud, comme dans l'exemple suivant :

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url] \
    --custom-certificate-authority-roots=[CA_NAME]

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 :

Appelez votre nouveau fournisseur de types dans une configuration.
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 types spécifié.
Effectuez la mise à jour de chaque collection.
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

Apprendre à appeler un fournisseur de types
Partager votre fournisseur de types avec d'autres projets
En savoir plus sur les types
Découvrir comment créer une configuration
Créer un déploiement
En savoir plus sur les options d'API avancées