Migrer de DownstreamWebApi vers DownstreamApi

Passer en revue l’historique de l’interface

Microsoft. Identity.Web 1.x a introduit IDownstreamWebApi, interface qui gère les détails de l’authentification (acquisition de jetons, en-têtes d’autorisation) lors de l’appel d’API. À mesure que l’interface s'est développée en fonction des demandes de fonctionnalités, des modifications majeures sont devenues nécessaires pour couvrir tous les scénarios demandés.

Au lieu de modifier l’API existante, l’équipe a créé une nouvelle interface : IDownstreamApi. L’ancienne interface est déconseillée et tout le développement futur se concentre sur la nouvelle implémentation. Vous pouvez migrer à votre propre rythme.

Cet article explique :

  • Comment migrer d’IDownstreamWebApi vers IDownstreamApi
  • Différences entre IDownstreamWebApi et IDownstreamApi

Migrer d’IDownstreamWebApi vers IDownstreamApi

Pour migrer de IDownstreamWebApi vers Microsoft. Identity.Web 2.x et IDownstreamApi :

  1. Ajoutez une référence au package NuGet Microsoft.Identity.Web.DownstreamApi.

  2. Dans le code d’initialisation de votre application ( généralement Startup.cs ou Program.cs), remplacez l’ancien appel d’inscription :

    .AddDownstreamWebApi("serviceName", Configuration.GetSection("SectionName"))

    avec le nouvel appel d’inscription :

    .AddDownstreamApi("serviceName", Configuration.GetSection("SectionName"))

  3. Dans le fichier de configuration (appsettings.json), dans la section représentant l’API web en aval, remplacez la valeur de Scopes de chaîne par un tableau de chaînes. L’exemple suivant montre le format de chaîne délimitée par l’espace d’origine :

    "DownstreamApi1": {
    "BaseUrl": "https://myapi.domain.com",
    "Scopes": "https://myapi.domain.com/read  https://myapi.domain.com/write"
},

    Mettez à jour les périmètres pour utiliser le nouveau format de tableau :

    "DownstreamApi1": {
    "BaseUrl": "https://myapi.domain.com",
    "Scopes": [
        "https://myapi.domain.com/read",
        "https://myapi.domain.com/write" 
    ]
},

    Avertissement

    Si vous oubliez de modifier les étendues en tableau, lorsque vous essayez d’utiliser IDownstreamApi, les étendues apparaîtront nulles, et IDownstreamApi tentera de faire un appel anonyme (non authentifié) à l'API en aval, ce qui entraînera une erreur 401 non authentifiée.

  4. Dans le contrôleur :

    • Ajouter using namespace Microsoft.Identity.Abstractions

    • Injecter IDownstreamApi au lieu de IDownstreamWebApi

    • Remplacez CallWebApiForUserAsync par CallApiForUserAsync

    • Si vous avez utilisé l’une des méthodes GetForUser, PutForUser ou PostForUser, modifiez la chaîne qui a exprimé le chemin d’accès relatif à un délégué qui définit ce chemin relatif. L’exemple suivant montre l'approche du paramètre de chaîne original :

      Todo value = await _downstreamWebApi.GetForUserAsync<Todo>(ServiceName,
                                                            $"api/todolist/{id}");

      Mettez à jour le code pour utiliser un délégué qui définit le chemin relatif :

      Todo value = await _downstreamWebApi.GetForUserAsync<Todo>(
      ServiceName,
      options => options.RelativePath = $"api/todolist/{id}";);

Passer en revue un exemple de code

L’exemple suivant montre comment utiliser IDownstreamApi dans une application de travail.

Consultez l’exemple complet : ASP.NET Core application web appelant l’API web/TodoListController.

Comparer IDownstreamWebApi et IDownstreamApi

Le tableau suivant récapitule les principales différences entre le déprécié IDownstreamWebApi et le nouveau IDownstreamApi:

Fonctionnalité IDownstreamWebApi (déconseillé) IDownstreamApi
Package NuGet Microsoft.Identity.Web.DownstreamWebApi Microsoft.Identity.Web.DownstreamApi
Inscription AddDownstreamWebApi() AddDownstreamApi()
Configuration des étendues Chaîne délimitée par l’espace Tableau de chaînes
Modèle d’options Limité Prise en charge complète Action<DownstreamApiOptions> des délégués
Chemin relatif Paramètre de chaîne Définir via un délégué des options (options.RelativePath)
Serialization Gestion manuelle des données JSON Sérialisation intégrée avec des génériques <TInput, TOutput>
Méthodes HTTP GetForUserAsync, PostForUserAsync, etc. Unifié CallApiForUserAsync avec la méthode HTTP dans les options, ainsi que des assistants typés
Appels d’application uniquement CallWebApiForAppAsync CallApiForAppAsync
Message HTTP personnalisé Non pris en charge options.CustomizeHttpRequestMessage déléguer
Options de clonage et de surcharge Non pris en charge Remplacements d’option par appel via le délégué
Abstraction de protocole Lié à Microsoft. Identity.Web Basé sur Microsoft.Identity.Abstractions (réutilisable dans les bibliothèques d’identités)

Comprendre les avantages de la migration

La migration vers IDownstreamApi vous permet d’accéder à des améliorations en cours et à une surface d’API plus flexible.

  • IDownstreamWebApi est déconseillé et ne recevra pas de nouvelles fonctionnalités ni correctifs de bogues.
  • IDownstreamApi fournit une surface d’API plus propre, une meilleure prise en charge de la sérialisation et une personnalisation complète des options.
  • La couche d'abstraction (Microsoft.Identity.Abstractions) signifie que votre code d'API en aval n'est pas étroitement couplé à une bibliothèque d'identité spécifique.

Explorer le contenu associé

Utilisez ces ressources pour en savoir plus sur l’appel d’API en aval.

  • Last updated on