Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
S'APPLIQUE À : Tous les niveaux de Gestion des API
Un service principal (ou API back-end) dans Gestion des API est un service HTTP qui implémente votre API frontale et ses opérations.
Lorsque vous importez certaines API, Gestion des API configure automatiquement le back-end d’API. Par exemple, API Management configure le service web back-end lors de l’importation :
- Une spécification OpenAPI.
- Une API SOAP.
Pour d’autres API, telles que les API des services Azure, vous importez une ressource Azure sans spécifier explicitement le service principal. Voici quelques exemples :
- Application de fonction Azure déclenchée par HTTP
- Application logique.
Gestion des API prend également en charge l’utilisation d’autres ressources en tant que back-end d’API, telles que :
- Un cluster Service Fabric.
- Services d’intelligence artificielle
- Un service personnalisé
Pour ces back-ends, vous pouvez créer une entité back-end dans Gestion des API et la référencer dans vos API.
Avantages des serveurs principaux
La Gestion des API prend en charge les entités de back-end personnalisés afin que vous puissiez gérer les services back-end de votre API. Une entité back-end encapsule des informations sur le service back-end, favorisant la réutilisation entre les API et améliorant la gouvernance.
Utilisez des back-ends pour une ou plusieurs des actions suivantes :
- Autoriser les informations d’identification des requêtes au service back-end
- Tirez parti de la fonctionnalité Gestion des API pour gérer les secrets dans Azure Key Vault si les valeurs nommées sont configurées pour l’authentification des paramètres d’en-tête ou de requête
- Définir des règles de disjoncteur pour protéger votre back-end contre un trop grand nombre de requêtes
- Acheminer ou équilibrer la charge des requêtes vers plusieurs back-ends
Configurez et gérez des entités back-end dans le portail Azure, ou à l’aide d’API ou d’outils Azure.
Création d'un serveur principal
Vous pouvez créer un back-end dans le portail Azure ou à l’aide d’API ou d’outils Azure.
Remarque
Lorsque vous importez certaines API, telles que les API de Microsoft Foundry ou d’autres services IA, Gestion des API configure automatiquement une entité back-end.
Pour créer un back-end dans le portail :
- Connectez-vous au portail et accédez à votre instance Gestion des API.
- Dans le menu de gauche, sélectionnez API>Backends>+ Créer un serveur principal.
- Dans la page Back-end , procédez comme suit :
- Entrez un nom pour le back-end et la description facultative.
- Sélectionnez un type d’hébergement principal, tel qu’une ressource Azure pour une ressource Azure comme une application de fonction ou une application logique, une URL personnalisée pour un service personnalisé ou un cluster Service Fabric .
- Dans l’URL du runtime, entrez l’URL du service principal vers lequel les demandes d’API sont transférées.
- Sous Avancé, désactivez éventuellement la validation de la chaîne de certificats ou du nom de certificat pour le serveur principal.
- Sous Ajouter ce service principal à un pool principal, sélectionnez ou créez éventuellement un pool à charge équilibrée pour le serveur principal.
- Sous règle de disjoncteur, configurez éventuellement un disjoncteur pour le back-end.
- Sous Informations d’identification d’autorisation, configurez éventuellement les informations d’identification pour autoriser l’accès au serveur principal. Les options incluent un en-tête de requête, un paramètre de requête, un certificat client ou une identité managée affectée par le système ou affectée par l’utilisateur configurée dans l’instance Gestion des API.
- Cliquez sur Créer.
Après avoir créé un back-end, vous pouvez mettre à jour les paramètres du back-end à tout moment. Par exemple, vous pouvez ajouter une règle de disjoncteur, modifier l’URL du runtime ou ajouter des informations d’identification d’autorisation.
Configurer l’identité gérée pour les certificats d'autorisation
Vous pouvez utiliser une identité managée affectée par le système ou affectée par l’utilisateur configurée dans l’instance Gestion des API pour autoriser l’accès au service principal. Pour configurer une identité managée pour les informations d’identification d’autorisation, procédez comme suit :
Dans la section Informations d’identification d’autorisation de la configuration back-end, sélectionnez l’onglet Identité managée , puis activez.
Dans l’identité du client, sélectionnez l’identité affectée par le système ou une identité affectée par l’utilisateur que vous avez configurée dans votre instance.
Dans l’ID de ressource, entrez un service Azure cible ou l’ID d’application de votre propre application Microsoft Entra représentant le back-end. Par exemple, entrez
https://cognitiveservices.azure.compour le service Azure OpenAI.Pour plus d’exemples, consultez la référence de stratégie d’authentification gérée par identité.
Cliquez sur Créer.
Remarque
Attribuez également à l’identité managée les autorisations appropriées ou un rôle RBAC pour accéder au service principal. Par exemple, si le back-end est un service Azure OpenAI, attribuez l’identité managée au Cognitive Services User rôle.
Configurer des certificats pour les informations d’identification d’autorisation
Vous pouvez sécuriser l’accès à la passerelle auprès du service back-end à l’aide de l’authentification TLS mutuelle avec des certificats clients ou des certificats d’autorité de certification (CA) personnalisée.
Configurer le certificat client
Si le service principal est sécurisé avec un certificat émis par une autorité de certification connue, vous pouvez ajouter un certificat client dans l’entité back-end :
- Ajoutez le certificat à l’instance Gestion des API. Vous pouvez référencer un certificat géré dans Azure Key Vault ou charger un fichier PFX.
- Dans la section Informations d’identification d’autorisation de la configuration back-end, sélectionnez l’onglet Certificats clients .
- Dans la liste déroulante, sélectionnez le certificat client que vous souhaitez utiliser.
- Cliquez sur Créer.
Configurer le certificat d’autorité de certification
Si le service principal utilise un certificat d’autorité de certification personnalisé, vous pouvez référencer le certificat d’autorité de certification personnalisé dans l’entité back-end. Vous devrez peut-être effectuer cette étape pour établir l’approbation du certificat de serveur principal , par exemple, avec des certificats auto-signés, des certificats racines non approuvés ou des chaînes de certificats partielles.
Remarque
Actuellement, seul le détail du certificat CA peut être configuré dans une entité back-end dans les niveaux v2.
Pour ajouter des détails sur le certificat d’autorité de certification, procédez comme suit :
- Dans la section Informations d’identification d’autorisation de la configuration back-end, sélectionnez Certificats d’autorité de certification.
- Sélectionnez + Ajouter les détails du certificat CA.
- Dans le volet Ajouter un certificat d’autorité de certification , sélectionnez l’une des options suivantes :
- Empreinte numérique du certificat : entrez l’empreinte numérique (un hachage SHA-1, SHA-256 ou SHA-512) d’un certificat d’autorité de certification personnalisé.
- Nom du sujet et empreinte de l’émetteur : entrez le nom du sujet qui identifie de manière unique l’autorité de certification et l’empreinte de l’autorité de certification.
- Sélectionnez Ajouter.
- Cliquez sur Créer.
Remarque
Lorsque vous configurez les détails d’un certificat d’autorité de certification personnalisé dans l’entité back-end, Gestion des API valide toujours le nom du certificat et la chaîne de certificats, que vous activiez ou désactivez les paramètres de validation dans le serveur principal backendTlsProperties.
Conseil / Astuce
Vous pouvez également configurer les détails du certificat d’autorité de certification par programme à l’aide de l’API REST Gestion des API. Définissez backendTlsProperties dans l’entité backend.
Référencer le back-end à l’aide de la stratégie set-backend-service
Après avoir créé un back-end, vous pouvez référencer l’identificateur principal (nom) dans vos API. Utilisez la stratégie set-backend-service pour diriger une requête d’API entrante vers le back-end. Si vous avez déjà configuré un service web principal pour une API, vous pouvez utiliser la stratégie set-backend-service pour rediriger la requête vers une entité back-end à la place. Exemple :
<policies>
<inbound>
<base />
<set-backend-service backend-id="myBackend" />
</inbound>
[...]
<policies/>
Remarque
Vous pouvez également utiliser base-url. En règle générale, le format est https://backend.com/api. Évitez d’ajouter une barre oblique à la fin pour empêcher les erreurs de configuration. En règle générale, la valeur de base-url et la valeur du point de terminaison HTTP(S) dans le back-end doivent correspondre pour permettre une intégration transparente entre le serveur frontal et le serveur principal. Notez que les instances de la Gestion des API ajoutent le nom du service principal à base-url.
Vous pouvez utiliser la logique conditionnelle avec la stratégie set-backend-service pour modifier le back-end effectif en fonction de l’emplacement, de la passerelle appelée ou d’autres expressions.
Par exemple, voici une stratégie permettant d’acheminer le trafic vers un autre back-end en fonction de la passerelle appelée :
<policies>
<inbound>
<base />
<choose>
<when condition="@(context.Deployment.Gateway.Id == "factory-gateway")">
<set-backend-service backend-id="backend-on-prem" />
</when>
<when condition="@(context.Deployment.Gateway.IsManaged == false)">
<set-backend-service backend-id="self-hosted-backend" />
</when>
<otherwise />
</choose>
</inbound>
[...]
<policies/>
Conseil / Astuce
Gestion des API détecte et utilise également automatiquement les entités principales lorsqu’elle reçoit des demandes d’API. Au moment de l’exécution, s’il existe une entité back-end qui correspond à l’URL d’un service back-end auquel Gestion des API envoie une requête, elle utilise l’entité back-end. Vous n’avez pas besoin d’utiliser set-backend-serviceexplicitement .
Disjoncteur
Gestion des API expose une propriété de disjoncteur dans la ressource back-end pour protéger un service back-end d’une submersion par trop de requêtes.
- La propriété du disjoncteur définit les règles de déclenchement du disjoncteur, telles que le nombre ou le pourcentage de conditions de défaillance pendant un intervalle de temps défini et une plage de codes d’état indiquant les défaillances.
- Lorsque le disjoncteur se déclenche, API Management cesse d’envoyer des requêtes au service back-end pendant une durée définie et renvoie une réponse 503 Service indisponible au client.
- Une fois la durée du cycle configurée écoulée, le circuit se réinitialise et le trafic reprend vers le back-end.
Le disjoncteur du back-end est une implémentation du modèle de disjoncteur qui permet au back-end de se remettre de situations de surcharge. Il complète les politiques générales de limitation de débit et de limitation de concurrence que vous pouvez implémenter pour protéger la passerelle de la gestion des API et de vos services back-end.
Remarque
- Actuellement, le disjoncteur de back-end n’est pas pris en charge au niveau Consommation de la Gestion des API.
- En raison de la nature distribuée de l’architecture de la Gestion des API, les règles de déclenchement du disjoncteur sont approximatives. Différentes instances de la passerelle ne se synchronisent pas et appliquent des règles de disjoncteur en fonction des informations sur la même instance.
- Actuellement, vous ne pouvez configurer qu’une seule règle pour un disjoncteur principal.
Avertissement
Si vous configurez un service Azure OpenAI en tant que back-end et que le service reçoit trop de demandes, il retourne un 429 Too Many Requests code d’état de réponse et un Retry-After en-tête avec une valeur pouvant être volumineuse (par exemple, 1 jour). Avec les back-ends Azure OpenAI, implémentez des règles de disjoncteur pour gérer les réponses 429 et accepter la durée Retry-After.
Exemple
Utilisez le portail Azure, l’API REST Gestion des API ou un modèle Bicep ou ARM pour configurer un disjoncteur dans un back-end. Dans l’exemple suivant, le disjoncteur dans myBackend, dans l’instance Gestion des API myAPIM, se déclenche lorsqu’il existe trois codes d’état 5xx (ou plus) indiquant des erreurs de serveur en une heure.
Le disjoncteur de cet exemple se réinitialise après 1 heure. Si un en-tête Retry-After est présent dans la réponse, le disjoncteur accepte la valeur et attend l’heure spécifiée avant l’envoi de nouvelles requêtes au back-end.
- Dans le portail Azure, accédez à votre instance Gestion des API.
- Dans le menu de gauche, sélectionnez les> APIBack-ends> de votre back-end.
- Dans la page back-end, sélectionnez Paramètres>Paramètres du disjoncteur>Ajouter un nouveau.
- Dans la page Créer un disjoncteur , configurez la règle :
- Nom de la règle : entrez un nom pour la règle, par exemple myBackend.
- Nombre d’échecs : entrez 3.
- Intervalle d’échec : conservez la valeur par défaut de 1 heure.
- Plage de codes d’état d’échec : sélectionnez 500 à 599.
- Durée du trajet : conservez la valeur par défaut de 1 heure.
- Cochez l’en-tête « Retry-After » dans la réponse HTTP : Sélectionnez True (Accepter).
Pool à équilibrage de charge
Gestion des API prend en charge les pools principaux lorsque vous souhaitez implémenter plusieurs back-ends pour une API et équilibrer la charge des requêtes entre ces back-ends. Un pool est une collection de back-ends qui sont traités comme une entité unique pour l’équilibrage de charge.
Utilisez un pool principal pour les scénarios tels que les scénarios suivants :
- Répartissez la charge sur plusieurs backends, qui peuvent avoir des disjoncteurs individuels.
- Déplacez la charge d’un ensemble de back-ends vers un autre ensemble pour la mise à niveau (déploiement bleu-vert).
Remarque
- Vous pouvez inclure jusqu’à 30 back-ends par pool.
- En raison de la nature distribuée de l’architecture de Gestion des API, l’équilibrage de charge de back-end est approximatif. Différentes instances de la passerelle ne synchronisent pas et n’équilibrent pas la charge en fonction des informations sur la même instance.
Options d’équilibrage de charge
Gestion des API prend en charge les options d’équilibrage de charge suivantes pour les pools back-end :
| Option d’équilibrage de charge | Descriptif |
|---|---|
| Tourniquet (round robin) | Les requêtes sont distribuées uniformément entre les back-ends du pool par défaut. |
| Pondéré | Affectez des pondérations aux back-ends du pool et distribuez les requêtes en fonction du poids relatif de chaque back-end. Utile pour les scénarios tels que les déploiements bleu-vert. |
| Basé sur la priorité | Organisez les back-ends en groupes de priorité. Envoyer d’abord des demandes à des groupes de priorité supérieure ; au sein d’un groupe, distribuez les demandes uniformément ou en fonction des pondérations attribuées. |
Remarque
Le service Gestion des API utilise des back-ends dans les groupes de priorité inférieure seulement lorsque tous les back-ends des groupes de priorité supérieure ne sont pas disponibles, car les règles de disjoncteur sont triplées.
Sensibilisation à la session
Avec l’une des options d’équilibrage de charge précédentes, vous pouvez activer la prise en charge de la session (affinité de session) pour vous assurer que toutes les demandes d’un utilisateur spécifique pendant une session accèdent au même back-end dans le pool. Gestion des API définit un cookie d’ID de session pour maintenir l’état de session. Cette option est utile, par exemple, dans les scénarios avec des back-ends tels que des assistants de conversation IA ou d’autres agents conversationnels pour acheminer les demandes de la même session vers le même point de terminaison.
Remarque
La sensibilisation à la session dans les pools à charge équilibrée est publiée en premier dans le groupe de mises à jouranticipées de la passerelle AI.
Gérer les cookies pour la sensibilisation à la session
Lorsque vous utilisez la sensibilisation à la session, le client doit gérer les cookies de manière appropriée. Le client doit stocker la valeur d’en-tête et l’envoyer avec les demandes suivantes pour maintenir l’état Set-Cookie de session.
Vous pouvez utiliser des stratégies Gestion des API pour vous aider à définir des cookies pour la sensibilisation à la session. Par exemple, pour le cas de l’API Assistants (fonctionnalité d’Azure OpenAI dans Microsoft Foundry Models), le client doit conserver l’ID de session, extraire l’ID de thread du corps et conserver la paire et envoyer le cookie approprié pour chaque appel. De plus, le client doit savoir quand envoyer un cookie ou quand ne pas envoyer un en-tête de cookie. Ces exigences peuvent être gérées de manière appropriée en définissant les exemples de stratégies suivants :
<policies>
<inbound>
<base />
<set-backend-service backend-id="APIMBackend" />
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
<set-variable name="gwSetCookie" value="@{
var payload = context.Response.Body.As<JObject>();
var threadId = payload["id"];
var gwSetCookieHeaderValue = context.Request.Headers.GetValueOrDefault("SetCookie", string.Empty);
if(!string.IsNullOrEmpty(gwSetCookieHeaderValue))
{
gwSetCookieHeaderValue = gwSetCookieHeaderValue + $";Path=/threads/{threadId};";
}
return gwSetCookieHeaderValue;
}" />
<set-header name="Set-Cookie" exists-action="override">
<value>Cookie=gwSetCookieHeaderValue</value>
</set-header>
</outbound>
<on-error>
<base />
</on-error>
</policies>
Exemple
Utilisez le portail, l’API REST Gestion des API ou un modèle Bicep ou ARM pour configurer un pool principal. Dans l’exemple suivant, le serveur principal myBackendPool dans l’instance de Gestion des API myAPIM est configuré avec un pool principal. Les exemples de back-end du pool sont nommés backend-1 et backend-2. Les deux back-ends se trouvent dans le groupe de priorité le plus élevé ; dans le groupe, backend-1 a un poids supérieur à backend-2.
- Dans le portail Azure, accédez à votre instance Gestion des API.
- Dans le menu de gauche, sélectionnez les> APIBack-ends> de votre back-end.
- Dans la page Back-ends , sélectionnez l’onglet Équilibreur de charge .
- Sélectionnez + Créer un pool.
- Dans la page Créer un pool à charge équilibrée , entrez les informations suivantes :
- Nom : entrez un nom pour le pool tel que myBackendPool.
- Description : Si vous le souhaitez, entrez une description.
- Ajouter des back-ends au pool : sélectionnez un ou plusieurs back-ends à ajouter au pool.
- Poids et priorité du back-end : sélectionnez Personnaliser l’épaisseur et la priorité pour configurer l’épaisseur et la priorité de chaque back-end du pool. Par exemple, si vous avez ajouté deux back-ends nommés backend-1 et backend-2, définissez le poids du back-1 sur 3 et le poids du back-end-2 à 1 et définissez la priorité des deux back-ends sur 1.
- Cliquez sur Créer.
Limites
- Pour les niveaux Développeur et Premium, une instance Gestion des API déployée dans un réseau virtuel interne peut générer des erreurs HTTP 500
BackendConnectionFailurequand l’URL du point de terminaison de passerelle et l’URL du back-end sont identiques. Si vous rencontrez cette limitation, suivez les instructions fournies dans l’article Limitation des demandes de la Gestion des API autochaînées en mode réseau virtuel interne du blog de la communauté technique. - Actuellement, vous ne pouvez configurer qu’une seule règle pour un disjoncteur principal.
Contenu connexe
- Blog : Utilisation du disjoncteur Gestion des API Azure et de l’équilibrage de charge avec Azure OpenAI Service
- Configurez un serveur principal Service Fabric à l’aide du portail Azure.
- Guide de démarrage rapide Créer un pool principal dans la Gestion des API Azure à l’aide de Bicep pour équilibrer la charge des requêtes OpenAI
- Consultez Gestion des API Azure comme source Event Grid pour plus d’informations sur les événements Event Grid générés par la passerelle lorsqu’un disjoncteur effectue des déplacements ou des réinitialisations. Utilisez ces événements pour prendre des mesures avant l’escalade des problèmes principaux.