Partager via

Serveurs principaux dans Gestion des API

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.

Lors de l’importation de certaines API, Gestion des API configure automatiquement l’API back-end. Par exemple, le service Gestion des API configure le service web back-end lors de l’importation :

La Gestion des API prend également en charge l’utilisation d’autres ressources Azure, comme un back-end d’API, par exemple :

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
  • Utilisez la fonctionnalité de Gestion des API pour gérer les secrets dans Azure Key Vault si des valeurs nommées sont configurées pour l’authentification de paramètre de requête ou d’en-tê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 les entités back-end personnalisés dans le Portail Azure, ou bien à 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.

Pour créer un back-end dans le portail :

  1. Connectez-vous au portail et accédez à votre instance Gestion des API.
  2. Dans le menu de gauche, sélectionnez API>Backends>+ Créer un serveur principal.
  3. Dans la page Back-end , procédez comme suit :
    1. Entrez un nom pour le back-end et la description facultative.
    2. Sélectionnez un type d’hébergement principal, par exemple, une ressource Azure pour une ressource Azure telle qu’une application de fonction ou une application logique, une URL personnalisée pour un service personnalisé ou un cluster Service Fabric .
    3. Dans l’URL du runtime, entrez l’URL du service principal vers lequel les demandes d’API sont transférées.
    4. Sous Avancé, désactivez éventuellement la validation de la chaîne de certificats ou du nom de certificat pour le serveur principal.
    5. Sous Ajouter ce service principal à un pool principal, sélectionnez ou créez éventuellement un pool à charge équilibrée pour le serveur principal.
    6. Sous règle de disjoncteur, configurez éventuellement un disjoncteur pour le back-end.
    7. 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.
    8. 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, ajoutez une règle de disjoncteur, modifiez l’URL du runtime ou ajoutez 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 :

  1. Dans la section Informations d’identification d’autorisation de la configuration back-end, sélectionnez l’onglet Identité managée , puis activez.

  2. Dans l’identité du client, sélectionnez l’identité affectée par le système ou une identité affectée par l’utilisateur configurée dans votre instance.

  3. 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. Exemple : https://cognitiveservices.azure.com pour le service Azure OpenAI.

    Pour plus d’exemples, consultez la référence de stratégie d’authentification gérée par identité.

  4. 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, vous pouvez affecter l’identité managée au Cognitive Services User rôle.

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. Par 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/>

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é disjoncteur définit des règles pour effectuer le déclenchement du disjoncteur, telles que le nombre ou le pourcentage de conditions d’échec pendant un intervalle de temps défini et une plage d’état des codes qui indiquent des défaillances.
  • Lorsque le disjoncteur se déclenche, la gestion des API arrête d’envoyer des requêtes au service back-end pendant une durée définie et retourne une réponse 503 Service Indisponible au client.
  • Après la durée du trajet configuré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 pour permettre au back-end de se rétablir après des situations de surcharge. Il augmente les stratégies 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, une seule règle peut être configurée pour un disjoncteur de back-end.

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.

  1. Dans le portail Azure, accédez à votre instance Gestion des API.
  2. Dans le menu de gauche, sélectionnez les> APIBack-ends> de votre back-end.
  3. Dans la page back-end, sélectionnez Paramètres>Paramètres du disjoncteur>Ajouter un nouveau.
  4. 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 back-ends, 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 de back-ends pour des scénarios tels que les suivants :

  • Répartir la charge sur plusieurs back-ends, ce qui peut avoir des disjoncteurs de back-end individuels.
  • Déplacer la charge d’un ensemble de back-ends vers un autre 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 se synchronisent pas et équilibrent 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é Les pondérations sont affectées aux back-ends du pool, et les requêtes sont distribuées 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é Les backends sont organisés en groupes de priorité. Les demandes sont envoyées d’abord à des groupes de priorité supérieure ; au sein d’un groupe, les requêtes sont distribuées uniformément ou en fonction des pondérations attribuées.

Remarque

Les back-ends dans les groupes de priorité inférieure ne sont utilisés que 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, activez éventuellement 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 sont dirigées vers le 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

Lors de l’utilisation de 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 Azure AI 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.

  1. Dans le portail Azure, accédez à votre instance Gestion des API.
  2. Dans le menu de gauche, sélectionnez les> APIBack-ends> de votre back-end.
  3. Dans la page Back-ends , sélectionnez l’onglet Équilibreur de charge .
  4. Sélectionnez + Créer un pool.
  5. Dans la page Créer un pool à charge équilibrée , procédez comme suit :
    • 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

Contenu connexe