Cette page a été traduite par l'API Cloud Translation.

Publier des API à l'aide de l'API Edge

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Cette section explique comment utiliser l'API Edge pour créer des produits d'API à publier sur les portails des développeurs.

Créer des produits d'API à l'aide de l'API

Les produits d'API permettent aux développeurs d'enregistrer des applications qui utilisent des API à l'aide de clés API et de jetons d'accès OAuth. Ils sont conçus pour regrouper les ressources d'API et les publier auprès de différents groupes de développeurs. Par exemple, vous devrez peut-être publier un ensemble de ressources d'API auprès de vos développeurs partenaires et un autre ensemble auprès de développeurs externes. Les produits d'API vous permettent d'effectuer directement ce regroupement, sans avoir à modifier vos API. Ils présentent un autre avantage : l'accès des développeurs peut être mis à jour et rétrogradé sans qu'ils n'aient à obtenir de nouvelles clés client pour leurs applications.

Pour créer un produit d'API à l'aide de l'API, envoyez une requête POST à /organizations/{org_name}/apiproducts. Pour en savoir plus, consultez la documentation de référence de l'API Créer un produit d'API.

La requête suivante crée un produit d'API nommé weather_free. Le produit d'API permet d'accéder à toutes les API exposées par le proxy d'API weatherapi déployé dans l'environnement test. Le type d'approbation est défini sur auto, ce qui indique que toute demande d'accès est approuvée.

curl -X POST https://api.enterprise.apigee.com/v1/organization/myorg/apiproducts \
-H "Content-Type:application/json" \
-d \
'{
  "approvalType": "auto",
  "displayName": "Free API Product",
  "name": "weather_free",
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ]
}' \
-u email:password

Exemple de réponse :

{
  "apiResources" : [ ],
  "approvalType" : "auto",
  "attributes" : [ ],
  "createdAt" : 1362759663145,
  "createdBy" : "developer@apigee.com",
  "displayName" : "Free API Product",
  "environments" : [ "test" ],
  "lastModifiedAt" : 1362759663145,
  "lastModifiedBy" : "developer@apigee.com",
  "name" : "weather_free",
  "proxies" : [ "weatherapi" ],
  "scopes" : [ ]
}

Le produit d'API créé ci-dessus met en œuvre le scénario le plus basique, qui autorise les requêtes adressées à un proxy d'API dans un environnement. Il définit un produit d'API permettant à une application autorisée d'accéder à toutes les ressources d'API accessibles via le proxy d'API exécuté dans l'environnement de test. Les produits d'API fournissent des paramètres de configuration supplémentaires qui vous permettent de personnaliser le contrôle des accès à vos API pour différents groupes de développeurs. Par exemple, vous pouvez créer deux produits d'API permettant d'accéder à plusieurs proxys d'API. Vous pouvez également créer deux produits d'API qui donnent accès aux mêmes proxys d'API, mais avec des paramètres de quota différents.

Paramètres de configuration des produits d'API

Les produits d'API proposent les options de configuration suivantes :

Nom	Description	Par défaut	Obligatoire ?
`apiResources`	Liste d'URI ou de chemins d'accès aux ressources séparés par une virgule, regroupés dans le produit d'API. Par défaut, les chemins d'accès aux ressources sont mappés à partir de la variable `proxy.pathsuffix`. Le suffixe du chemin du proxy correspond au fragment d'URI suivant le chemin de base ProxyEndpoint. Par exemple, dans l'exemple de produit d'API ci-dessous, l'élément `apiResources` est défini sur `/forecastrss`. Comme le chemin de base défini pour ce proxy d'API est `/weather`, cela signifie que seules les requêtes adressées à `/weather/forecastrss` sont autorisées par ce produit d'API. Vous pouvez sélectionner un chemin spécifique ou tous les sous-chemins avec un caractère générique. Les caractères génériques (/** et /) sont acceptés. Le caractère générique double astérisque indique que tous les sous-URI sont inclus. Un seul astérisque indique que seuls les URI d'un niveau inférieur sont inclus. Par défaut, "'/" accepte les mêmes ressources que "/*", ainsi que le chemin de base défini par le proxy d'API. Par exemple, si le chemin de base du proxy d'API est /v1/weatherapikey, le produit d'API accepte les requêtes adressées à /v1/weatherapikey et tous les sous-URI, tels que /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA, etc. Pour en savoir plus sur la modification du comportement de cette valeur par défaut, consultez la page Gérer les produits d'API.	ND	Non
`approvalType`	Indique l'approbation des clés API pour accéder aux API définies par le produit d'API. Si cette option est définie sur `manual`, la clé générée pour l'application est à l'état "En attente". Ces clés ne fonctionnent pas tant qu'elles ne sont pas explicitement approuvées. Si la valeur est `auto`, toutes les clés sont générées à l'état "Approuvé" et fonctionnent immédiatement. (`auto` sert généralement à donner accès à des produits d'API gratuits/en version d'essai offrant un quota ou des fonctionnalités limités.)	ND	Oui
`attributes`	Tableau d'attributs permettant d'étendre le profil du produit d'API par défaut avec des métadonnées spécifiques au client. Cette propriété vous permet de définir le niveau d'accès public, privé ou interne du produit d'API. Exemple : "attributes": [ { <ph type="x-smartling-placeholder"></ph> "name": "access", <ph type="x-smartling-placeholder"></ph> "value": "public" }, { <ph type="x-smartling-placeholder"></ph> "name": "foo", "value": "foo" }, { "name": "bar", "value": "bar" } ]	ND	Non
`scopes`	Liste des champs d'application OAuth séparés par une virgule et validés lors de l'exécution. (Apigee Edge vérifie que les champs d'application de tout jeton d'accès présenté correspondent à ceux définis dans l'API product.)	N/A	Non
`proxies`	Proxys d'API nommés auxquels le produit d'API est associé. Lorsque vous spécifiez des proxys, vous pouvez associer des ressources du produit d'API à des proxys d'API spécifiques afin d'empêcher les développeurs d'accéder à ces ressources via d'autres proxys d'API.	ND	Non. Si cette option n'est pas définie, vous devez explicitement spécifier `apiResources` (consultez les informations sur `apiResources` ci-dessus) et la variable `flow.resource.name` dans la règle AssignMessage.
`environments`	Environnements nommés ("test" ou "prod", par exemple) auxquels le produit d'API est associé. Lorsque vous spécifiez un ou plusieurs environnements, vous pouvez associer les ressources répertoriées dans le produit d'API à un environnement spécifique afin d'empêcher les développeurs d'accéder à ces ressources via des proxys d'API d'un autre environnement. Ce paramètre permet, par exemple, d'empêcher les proxys d'API déployés dans l'environnement "test" d'accéder aux ressources associées aux proxys d'API de l'environnement "prod".	ND	Non. Si cette option n'est pas définie, vous devez explicitement spécifier `apiResources` et la variable `flow.resource.name` dans la règle AssignMessage.
`quota`	Nombre de requêtes autorisées par application dans l'intervalle de temps spécifié.	ND	Non
`quotaInterval`	Nombre d'unités de temps pendant lesquelles les quotas sont évalués.	ND	Non
`quotaTimeUnit`	Unité de temps (minute, heure, jour ou mois) pendant laquelle les quotas sont comptabilisés.	ND	Non

Voici un exemple plus détaillé de création d'un produit d'API.

curl -X POST  https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts \
-H "Content-Type:application/json" -d \
'{
  "apiResources": [ "/forecastrss" ],
  "approvalType": "auto", 
  "attributes":
    [ {"name": "access", "value": "public"} ],
  "description": "Free API Product",
  "displayName": "Free API Product",
  "name": "weather_free",
  "scopes": [],
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ],
  "quota": "10",
  "quotaInterval": "2",
  "quotaTimeUnit": "hour" }' \
-u email:password

Exemple de réponse

{
  "apiResources" : [ "/forecastrss" ],
  "approvalType" : "auto",
  "attributes" : [ {
    "name" : "access",
    "value" : "public"
  },
  "createdAt" : 1344454200828,
  "createdBy" : "admin@apigee.com",
  "description" : "Free API Product",
  "displayName" : "Free API Product",
  "lastModifiedAt" : 1344454200828,
  "lastModifiedBy" : "admin@apigee.com",
  "name" : "weather_free",
  "scopes" : [ ],
  "proxies": [ {'weatherapi'} ],
  "environments": [ {'test'} ],
  "quota": "10",
  "quotaInterval": "1",
  "quotaTimeUnit": "hour"}'
}

À propos des champs d'application

Un champ d'application est un concept issu de OAuth correspondant approximativement au concept d'"autorisation". Activé Apigee Edge, les champs d'application sont entièrement facultatifs. Les champs d'application vous permettent d'appliquer des autorisations plus précises. Chaque clé client attribuée à une application est associée à un "champ d'application maître". Le champ d'application maître correspond à l'ensemble des champs d'application de tous les produits d'API pour lesquels l'application a été approuvée. Pour les applications autorisées à utiliser plusieurs produits d'API, le champ d'application maître combine tous les champs d'application définis dans les produits d'API pour lesquels la clé client a été approuvée.

Afficher les produits d'API

Pour afficher les produits d'API créés pour une organisation à l'aide de l'API, consultez les sections suivantes :

Afficher les produits d'API(monétisés)
Par défaut, seuls les produits d'API monétisés sont affichés (c'est-à-dire, les produits d'API disposant au moins d'un plan tarifaire publié). Pour afficher tous les produits d'API, définissez le paramètre de requête monetized sur false. Cela équivaut à envoyer une requête GET à la liste des produits d'API non monétisés : https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true
Afficher les produits d'API (non monétisés)
Afficher les produits d'API dont peuvent bénéficier les développeurs
Afficher les produits d'API dont peuvent bénéficier les entreprises

Vous trouverez ci-dessous un exemple décrivant comment afficher des produits d'API à l'aide de l'API :

curl -X GET "https://ext.apiexchange.org/v1/mint/organizations/{org_name}/products?monetized=true" \
  -H "Accept:application/json" \
  -u email:password

La réponse doit se présenter comme suit (seule une partie de la réponse est affichée) :

{
  "product" : [ {
    "customAtt1Name" : "user",
    "customAtt2Name" : "response size",
    "customAtt3Name" : "content-length",
    "description" : "payment api product",
    "displayName" : "payment",
    "id" : "payment",
    "name" : "payment",
    "organization" : {
      ...
    },
    "pricePoints" : [ ],
    "status" : "CREATED",
    "transactionSuccessCriteria" : "status == 'SUCCESS'"
  }, {
    "customAtt1Name" : "user",
    "customAtt2Name" : "response size",
    "customAtt3Name" : "content-length",
    "description" : "messaging api product",
    "displayName" : "messaging",
    "id" : "messaging",
    "name" : "messaging",
    "organization" : ...
    },
    "pricePoints" : [ ],
    "status" : "CREATED",
    "transactionSuccessCriteria" : "status == 'SUCCESS'"
  } ],
  "totalRecords" : 2
}

Enregistrer des développeurs à l'aide de l'API

Chaque application appartient à un développeur ou à une entreprise. Par conséquent, pour créer une application, vous devez d'abord enregistrer un développeur ou une entreprise.

Les développeurs doivent créer un profil pour s'enregistrer dans une organisation. Notez que le développeur l'adresse e-mail incluse dans le profil est utilisée comme clé unique pour le développeur tout au long Apigee Edge.

Pour gérer la monétisation, vous devez définir les attributs de monétisation lors de la création ou de la modification du profil des développeurs. Vous pouvez aussi définir d'autres à utiliser dans les analyses personnalisées, l'application des règles personnalisées, etc. ; ces valeurs arbitraires ne seront pas interprétés par Apigee Edge,

Par exemple, la requête suivante enregistre un profil pour un développeur dont l'adresse e-mail est ntesla@theremin.com et définit un sous-ensemble de la monétisation à l'aide de l'API Create developer:

$ curl -H "Content-type:application/json" -X POST -d \
'{"email" : "ntesla@theremin.com", 
  "firstName" : "Nikola", 
  "lastName" : "Tesla", 
  "userName" : "theremin", 
  "attributes" : [ 
  { 
    "name" : "project_type", 
    "value" : "public"
  },
  {    
   "name": "MINT_BILLING_TYPE",
   "value": "POSTPAID"
  },
  {
   "name": "MINT_DEVELOPER_ADDRESS",
   "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
  },
  {
   "name": "MINT_DEVELOPER_TYPE",
   "value": "TRUSTED"
  },
  {    
   "name": "MINT_HAS_SELF_BILLING,
   "value": "FALSE"
  },
  {
   "name" : "MINT_SUPPORTED_CURRENCY",
   "value" : "usd"
  }
 ] 
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers \
-u email:password

Exemple de réponse

{
          "email" : "ntesla@theremin.com",
          "firstName" : "Nikola",
          "lastName" : "Tesla",
          "userName" : "theremin",
          "organizationName" : "{org_name}",
          "status" : "active",
          "attributes" : [ 
          {
            "name" : "project_type",
            "value" : "public"
          },
          {    
             "name": "MINT_BILLING_TYPE",
             "value": "POSTPAID"
          },
          {
             "name": "MINT_DEVELOPER_ADDRESS",
             "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
          },
          {
             "name": "MINT_DEVELOPER_TYPE",
             "value": "TRUSTED"
          },
          {    
             "name": "MINT_HAS_SELF_BILLING,
             "value": "FALSE"
          },
          {
             "name" : "MINT_SUPPORTED_CURRENCY",
             "value" : "usd"
          } 
          ],
          "createdAt" : 1343189787717,
          "createdBy" : "admin@apigee.com",
          "lastModifiedAt" : 1343189787717,
          "lastModifiedBy" : "admin@apigee.com"
        }

Enregistrer des applications développeur à l'aide de l'API

Chaque application enregistrée sur Apigee Edge est associée à un développeur et à un produit d'API. Lorsqu'une application est enregistrée au nom d'un développeur, Apigee Edge génère des "identifiants". (un clé client et clé secrète) qui identifie l'application. L'application doit ensuite transmettre ces identifiants dans chaque requête adressée à un produit d'API associé à l'application.

La requête suivante utilise le bouton Créer Developer App pour enregistrer une application pour le développeur que vous avez créé ci-dessus: ntesla@theremin.com. Lorsque vous enregistrez une application, vous définissez un nom pour celle-ci, une valeur callbackUrl et une liste d'une ou plusieurs API. produits:

$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "weather_free"], 
  "callbackUrl" : "login.weatherapp.com", 
  "keyExpiresIn" : "2630000000",
  "name" : "weatherapp"}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps \
-u email:password

L'URL callbackUrl permet à certains types d'authentification OAuth (tels que le code d'autorisation) de valider les requêtes de redirection depuis l'application. Si vous utilisez OAuth, cette valeur doit être identique à celle définie dans l'URI redirect_uri utilisé pour envoyer des requêtes OAuth.

L'attribut keyExpiresIn spécifie, en millisecondes, la durée de vie de la clé client générée pour l'application développeur. La valeur par défaut, -1, indique une période de validité illimitée.

Exemple de réponse

{
  "appId": "5760d130-528f-4388-8c6f-65a6b3042bd1",
  "attributes": [
    {
      "name": "DisplayName",
      "value": "Test Key Expires"
    },
    {
      "name": "Notes",
      "value": "Just testing this attribute"
    }
  ],
  "createdAt": 1421770824390,
  "createdBy": "wwitman@apigee.com",
  "credentials": [
    {
      "apiProducts": [
        {
          "apiproduct": "ProductNoResources",
          "status": "approved"
        }
      ],
      "attributes": [],
      "consumerKey": "jcAFDcfwImkJ19A5gTsZRzfBItlqohBt",
      "consumerSecret": "AX7lGGIRJs6s8J8y",
      "expiresAt": 1424400824401,
      "issuedAt": 1421770824401,
      "scopes": [],
      "status": "approved"
    }
  ],
  "developerId": "e4Oy8ddTo3p1BFhs",
  "lastModifiedAt": 1421770824390,
  "lastModifiedBy": "wwitman@apigee.com",
  "name": "TestKeyExpires",
  "scopes": [],
  "status": "approved"
}

Gérer les clés client des applications à l'aide de l'API

Obtenir la clé client (clé API) de l'application

Les identifiants d'une application (produit d'API, clé client et code secret) sont renvoyés dans le profil d'application. L'administrateur d'une organisation peut récupérer la clé client à tout moment.

Le profil d'application affiche la valeur de la clé client et du code secret, l'état de la clé client, ainsi que les produits d'API associés à la clé. En tant qu'administrateur, vous pouvez récupérer le profil de la clé client à tout moment à l'aide de l'API Get Key Details for a Developer App :

$ curl -X GET -H "Accept: application/json" \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password

Exemple de réponse

{
  "apiProducts" : [ {
    "apiproduct" : "weather_free",
    "status" : "approved"
  } ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Pour en savoir plus, consultez la page Obtenir des informations sur la clé d'une application développeur.

Ajouter un produit d'API à une application et à une clé

Pour mettre à jour une application afin d'ajouter un nouveau produit d'API, vous devez ajouter le produit d'API à la clé de l'application à l'aide de l'API Add API Product to Key. Pour en savoir plus, consultez la page Ajouter un produit d'API à la clé.

L'ajout d'un produit d'API à une clé d'application permet à l'application qui la contient d'accéder aux ressources d'API regroupées dans le produit d'API. L'appel de méthode suivant ajoute un nouveau produit d'API à une application :

$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "newAPIProduct"]
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password

Exemple de réponse :

{
  "apiProducts": [
   {
     "apiproduct": "weather_free",
     "status": "approved"
   },
   {
     "apiproduct": "newAPIProduct",
     "status": "approved"
   }
 ],
 "attributes": [],
 "consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
 "consumerSecret": "1eluIIdWG3JGDjE0",
 "expiresAt": -1,
 "issuedAt": 1411491156464,
 "scopes": [],
 "status": "approved"
 }

Approuver les clés client

Le type d'approbation manual (manuel) vous permet de contrôler les développeurs pouvant accéder aux ressources protégées par les produits d'API. Lorsque l'approbation des clés est définie sur manual pour les produits d'API, les clés client doivent être explicitement approuvées. Les clés peuvent être explicitement approuvées à l'aide de l'API Approve or Revoke Specific Key of Developer App :

$ curl -X POST -H "Content-type:appilcation/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J?"action=approve" \
-u email:password

Exemple de réponse

{
  "apiProducts" : [ {
  "apiproduct" : "weather_free",
  "status" : "approved"
} ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Pour en savoir plus, consultez la page Approuver ou révoquer une clé spécifique de l'application développeur.

Approuver les produits d'API des clés client

Un état est également attribué à l'association d'un produit d'API à une clé client. Pour établir l'accès à l'API, la clé client doit être approuvée, y compris pour le produit d'API approprié. L'association d'une clé client à un produit d'API peut être approuvée à l'aide de l'API Approve or Revoke API Product for a Key for a Developer App :

$ curl -X POST -H "Content-type:application/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=approve" \
-u email:password

Cette commande cURL ne renvoie pas de réponse. Pour en savoir plus, consultez la page Approuver ou révoquer un produit d'API pour une clé d'application développeur.

Révoquer les produits d'API des clés client

Plusieurs raisons peuvent vous amener à révoquer l'association d'une clé client à un produit d'API. Vous devrez peut-être supprimer un produit d'API d'une clé client en raison d'un défaut de paiement d'un développeur, d'une période d'essai arrivée à expiration ou de la promotion d'une application d'un produit d'API à un autre.

Pour révoquer l'association d'une clé client à un produit d'API, utilisez l'API Approve or Revoke Specific Key of Developer App en effectuant l'action qui consiste à révoquer la clé client de l'application développeur :

$ curl -X POST -H "Content-type:application/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=revoke" \
-u email:password

Cette commande cURL ne renvoie pas de réponse. Pour en savoir plus, consultez la page Approuver ou révoquer une clé spécifique de l'application développeur.

Appliquer les paramètres des produits d'API

Pour appliquer des produits d'API, l'un des types de règles suivants doit être associé au flux du proxy d'API :

VerifyAPIKey : sélectionne une référence à une clé API, vérifie qu'elle représente une application valide et associe le produit d'API. Pour en savoir plus, consultez la page Règle VerifyAPIKey.
OAuthV1, opération “VerifyAccessToken” : vérifie la signature, valide un jeton d'accès OAuth 1.0a et une "clé client", et associe l'application au produit d'API. Pour en savoir plus, consultez la page Règle OAuth v1.0a.
OAuthV2, opération “VerifyAccessToken” : vérifie que le jeton d'accès OAuth 2.0 est valide, associe le jeton à l'application, vérifie que l'application est valide, puis associe l'application à un produit d'API. Pour en savoir plus, consultez la page Page d'accueil OAuth.

Une fois les règles et les produits d'API configurés, le processus suivant est exécuté par Apigee. Périphérie:

Une requête est reçue par Apigee Edge et acheminée vers le proxy d'API approprié.
Une règle est exécutée afin de vérifier la clé API ou le jeton d'accès OAuth présenté par le client.
Edge résout la clé API ou le jeton d'accès en un profil d'application.
Edge résout la liste (le cas échéant) des produits d'API associés à l'application.
Le premier produit d'API correspondant est utilisé pour renseigner des variables de quotas.
Si aucun produit d'API ne correspond à la clé API ou au jeton d'accès, la requête est rejetée.
Edge applique un contrôle d'accès basé sur l'URI (environnement, proxy d'API et chemin d'URI) en fonction de la les paramètres du produit d'API et les paramètres de quota.