כיצד להשתמש בגרסאות API ב- Core ASP.NET

כשאתה מפתח APIs, עליך לזכור דבר אחד: שינוי הוא בלתי נמנע. כאשר ה- API שלך הגיע לנקודה בה עליך להוסיף עוד אחריות, עליך לשקול גרסה של ה- API שלך. לפיכך תזדקק לאסטרטגיית גרסאות.

ישנן מספר גישות לגירסת ממשקי API, ולכל אחת מהן יתרונות וחסרונות. מאמר זה ידון באתגרים של גרסאות API וכיצד תוכלו לעבוד עם חבילת גרסאות ה- ASP.NET Core MVC של מיקרוסופט לגרסאות ה- API RESTful של גרסאות שנבנו ב- ASP.NET Core. תוכל לקרוא עוד על גרסאות Web API במאמר הקודם שלי כאן. 

צור פרויקט ASP.NET Core 3.1 API

ראשית, בואו ניצור פרויקט ליבה של ASP.NET ב- Visual Studio. בהנחה ש- Visual Studio 2019 מותקן במערכת שלך, בצע את הצעדים המתוארים להלן כדי ליצור פרויקט ASP.NET Core חדש ב- Visual Studio.

  1. הפעל את Visual Studio IDE.
  2. לחץ על "צור פרויקט חדש".
  3. בחלון "צור פרויקט חדש" בחר "ASP.NET יישום אינטרנט ליבה" מרשימת התבניות המוצגות.
  4. הקש "הבא.
  5. בחלון "הגדר את הפרויקט החדש שלך" שמוצג הבא, ציין את השם והמיקום של הפרויקט החדש.
  6. לחץ על צור.
  7. בחלון "צור יישום אינטרנט חדש של ASP.NET Core" בחר .NET Core בתור זמן הריצה ו- ASP.NET Core 3.1 (או מאוחר יותר) מהרשימה הנפתחת בחלק העליון. אני אשתמש כאן ב- ASP.NET Core 3.1.
  8. בחר "API" כתבנית הפרויקט ליצירת יישום API חדש של ASP.NET Core. 
  9. ודא שתיבות הסימון "אפשר תמיכה ב- Docker" ו- "הגדר עבור HTTPS" אינן מסומנות מכיוון שלא נשתמש בתכונות אלה כאן.
  10. ודא שהאימות מוגדר כ"אין אימות "מכיוון שלא נשתמש גם באימות.
  11. לחץ על צור. 

זה ייצור פרוייקט ASP.NET Core API חדש ב- Visual Studio. בחר בתיקיית הפיתרון של בקרים בחלון סייר הפיתרון ולחץ על "הוסף -> בקר ..." כדי ליצור בקר חדש בשם DefaultController.

החלף את קוד המקור של מחלקת DefaultController בקוד הבא.

    [Route ("api / [controller]")]

    [ApiController]

    מחלקה ציבורית DefaultController: ControllerBase

    {

        מחרוזת [] מחברים = מחרוזת חדשה []

        {"ג'וידיפ קנג'ילאל", "סטיב סמית", "סטיבן ג'ונס"};

        [HttpGet]

        מספר IE מספר Get ()

        {

            מחברים מחזירים;

        }

    }

נשתמש בבקר זה בסעיפים הבאים של מאמר זה.

כדי להטמיע גרסאות API ב- ASP.NET Core עליך לבצע את הפעולות הבאות:

  1. התקן את חבילת גרסאות ה- ASP.NET Core MVC.
  2. הגדר את גרסאות ה- API במחלקת ההפעלה.
  3. הביא הערה לבקרים ולפעולות עם תכונות מתאימות.

התקן את חבילת גרסאות ה- ASP.NET Core MVC

ASP.NET Core מספק תמיכה בגירסת API מהקופסה. כדי למנף גרסאות API, כל שעליך לעשות הוא להתקין את חבילת Microsoft.AspNetCore.Mvc.Versioning מ- NuGet. באפשרותך לעשות זאת באמצעות מנהל החבילות של NuGet בתוך Visual Studio 2019 IDE, או על ידי ביצוע הפקודה הבאה במסוף מנהל החבילות של NuGet:

התקנת חבילה Microsoft.AspNetCore.Mvc.Versioning

שים לב שאם אתה משתמש ב- API של ASP.NET Web, עליך להוסיף את חבילת Microsoft.AspNet.WebApi.Versioning.

הגדר תצורת גרסאות API ב- Core ASP.NET

כעת, לאחר שהותקנה בפרויקט שלך החבילה הדרושה לגירסת ה- API שלך, תוכל להגדיר גרסאות API בשיטת ConfigureServices של מחלקת ההפעלה. קטע הקוד הבא ממחיש כיצד ניתן להשיג זאת.

חלל ציבורי ConfigureServices (שירותי ISCollection)

{

  services.AddControllers ();

  services.AddApiVersioning ();

}

כשתגיש בקשה לקבל ל- API שלך, תוצג בפניך השגיאה המוצגת באיור 1.

כדי לפתור שגיאה זו, תוכל לציין את גרסת ברירת המחדל בעת הוספת שירותי הגירסאות של ה- API למיכל. אולי תרצה להשתמש בגרסת ברירת מחדל אם לא מוגדרת גרסה בבקשה. קטע הקוד הבא מראה כיצד ניתן להגדיר גרסת ברירת מחדל כ -1.0 באמצעות מאפיין AssumeDefaultVersionWhenUnspecified אם פרטי הגרסה אינם זמינים בבקשה.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = ApiVersion חדש (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

});

שים לב כיצד הגרסה העיקרית והגרסה המשנית מועברים לבנאי מחלקת ApiVersion בזמן הקצאת גרסת ברירת המחדל. המאפיין AssumeDefaultVersionWhenUnspecified יכול להכיל ערכי אמת או שקר. אם זה נכון, ישמש גרסת ברירת המחדל שצוינה בעת קביעת התצורה של גרסאות API אם לא קיים מידע על הגרסה.

קוד המקור השלם של שיטת ConfigureServices מופיע להלן לעיונך.

חלל ציבורי ConfigureServices (שירותי ISCollection)

{

    services.AddControllers ();

    services.AddApiVersioning (config =>

    {

         config.DefaultApiVersion = ApiVersion חדש (1, 0);

         config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

מכיוון שלא ציינת שום מידע על גרסאות, לכל נקודות הקצה תהיה גרסת ברירת המחדל 1.0.

דווח על כל הגרסאות הנתמכות של ה- API שלך

ייתכן שתרצה ליידע את הלקוחות של ה- API על כל הגרסאות הנתמכות. לשם כך, עליך לנצל את המאפיין ReportApiVersions כפי שמוצג בקטע הקוד המופיע למטה.

services.AddApiVersioning (config =>

{

  config.DefaultApiVersion = ApiVersion חדש (1, 0);

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = true;

});

השתמש בגרסאות בבקר ובשיטות פעולה

עכשיו בואו נוסיף כמה גרסאות נתמכות לבקר שלנו באמצעות תכונות כפי שמוצג בקטע הקוד המופיע להלן.

    [Route ("api / [controller]")]

    [ApiController]

    [ApiVersion ("1.0")]

    [ApiVersion ("1.1")]

    [ApiVersion ("2.0")]

    מחלקה ציבורית DefaultController: ControllerBase

    {

        מחרוזת [] מחברים = מחרוזת חדשה []

        {"ג'וידיפ קנג'ילאל", "סטיב סמית", "אנאנד ג'ון"};

        [HttpGet]

        מספר IE מספר Get ()

        {

            מחברים מחזירים;

        }

    }

כאשר אתה מגיש בקשת קבל מלקוח HTTP כגון דואר, כך ידווחו הגרסאות.

תוכל לדווח גם על הגרסאות שהוצאו משימוש. לשם כך, עליך להעביר פרמטר נוסף לשיטת ApiVersion כפי שמוצג בקטע הקוד המופיע למטה.

[ApiVersion ("1.0", הוצא משימוש = נכון)]

מפה לגרסה ספציפית של שיטת פעולה

יש מאפיין חשוב נוסף בשם MapToApiVersion. אתה יכול להשתמש בו כדי למפות לגרסה ספציפית של שיטת פעולה. קטע הקוד הבא מראה כיצד ניתן להשיג זאת.

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

מחרוזת ציבורית קבל (int id)

{

   מחברים מחזירים [מזהה];

}

דוגמה מלאה לגירסת API ב- Core ASP.NET

הנה קוד המקור השלם של DefaultController לעיונך.

[Route ("api / [controller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

מחלקה ציבורית DefaultController: ControllerBase

{

  מחרוזת [] מחברים = מחרוזת חדשה []

  {"ג'וידיפ קנג'ילאל", "סטיב סמית", "סטיבן ג'ונס"};

  [HttpGet]

  מספר IE מספר Get ()

  {

      מחברים מחזירים;

  }

  [HttpGet ("{id}")]

  [MapToApiVersion ("2.0")]

  מחרוזת ציבורית קבל (int id)

  {

     מחברים מחזירים [מזהה];

  }

}

אסטרטגיות גרסאות API ב- Core ASP.NET

ישנן מספר דרכים בהן אתה יכול לגרסא את ה- API שלך ב- ASP.NET Core. בחלק זה נחקור כל אחד מהם.

העבר מידע על גרסאות כפרמטרים של QueryString

במקרה זה, בדרך כלל תעביר את פרטי הגרסה כחלק ממחרוזת השאילתה, כפי שמוצג בכתובת האתר המופיעה למטה.

//localhost:25718/api/default?api-version=1.0

העבירו מידע על גרסאות בכותרות ה- HTTP

אם אתה מעביר מידע על גרסאות בכותרות HTTP, עליך להגדיר אותו בשיטת ConfigureServices כפי שמוצג בקטע הקוד המופיע להלן.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = ApiVersion חדש (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

   config.ReportApiVersions = true;

   config.ApiVersionReader = HeaderApiVersionReader חדש ("גרסת API");

});

לאחר הגדרת זה, תוכל להפעיל שיטת פעולה המתייחסת לגרסה ספציפית של ה- API כפי שמוצג באיור 3.

העבר מידע על גרסאות בכתובת האתר

שיטה נוספת להעברת מידע על הגרסה היא העברת מידע על הגרסה כחלק מהמסלול. זו הדרך הפשוטה ביותר לגירסא ל- API שלך, אך ישנם אזהרות מסוימות. ראשית, אם אתה משתמש באסטרטגיה זו, הלקוחות שלך יצטרכו לעדכן את כתובת האתר בכל פעם שפורסמה גרסה חדשה של ה- API. כתוצאה מכך, גישה זו שוברת עקרון בסיסי של REST הקובע כי כתובת ה- URL של משאב מסוים לעולם אינה צריכה להשתנות.

כדי ליישם אסטרטגיית גרסאות זו, עליך לציין את פרטי המסלול בבקר שלך כמוצג להלן.

[מסלול ("api / v {version: apiVersion} / [controller]")]

רישום הקוד הבא מראה כיצד ניתן להגדיר זאת בכיתת הבקר שלך.

[מסלול ("api / v {version: apiVersion} / [controller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

מחלקה ציבורית DefaultController: ControllerBase

    {

        מחרוזת [] מחברים = מחרוזת חדשה []

        {"ג'וידיפ קנג'ילאל", "סטיב סמית", "סטיבן ג'ונס"};

        [HttpGet]

        מספר IE מספר Get ()

        {

            מחברים מחזירים;

        }

        [HttpGet ("{id}")]

        [MapToApiVersion ("2.0")]

        מחרוזת ציבורית קבל (int id)

        {

            מחברים מחזירים [מזהה];

        }

    }

כך תוכל להתקשר ל- HTTP המוגדר כברירת מחדל כדי לקבל את השיטה של ​​מחלקת DefaultController.

//localhost:25718/api/v1.0/default

כדי להפעיל את שיטת HTTP GET האחרת, כלומר את זו שמקבלת פרמטר, ציין את הדברים הבאים בדפדפן האינטרנט או בלקוח HTTP כגון Postman.

//localhost:25718/api/v2.0/default/1

מחסול גרסה אחת או יותר של ה- API שלך

נניח שיש לך מספר גרסאות של ה- API שלך, אך ברצונך לשלול אחת או יותר מהן. אתה יכול לעשות זאת בקלות - אתה רק צריך לציין את המאפיין שהוצא משימוש של המחלקה ApiVersionAttribute ל- true כפי שמוצג בקטע הקוד המופיע למטה.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", הוצא משימוש = נכון)]

[ApiVersion ("2.0")]

מחלקה ציבורית DefaultController: ControllerBase

{

     // קוד רגיל

}

גרסאות ה- API ב- ASP.NET Core חלקות הודות להקדמת חבילת Microsoft.AspNetCore.Mvc.Versioning. ישנן מספר דרכים לגירסת ה- API שלך - אתה רק צריך להחליט על האסטרטגיה הטובה ביותר על פי הדרישות שלך. אתה יכול גם להשתמש בתוכניות גרסאות מרובות עבור ה- API שלך. זה מוסיף גמישות רבה מכיוון שהלקוחות יכולים לבחור בכל אחת מתוכניות הגירסאות הנתמכות.

כיצד לעשות יותר בליבת ASP.NET:

  • כיצד להשתמש באובייקטים של העברת נתונים ב- ASP.NET Core 3.1
  • כיצד לטפל ב 404 שגיאות ב- ASP.NET Core MVC
  • כיצד להשתמש בהזרקת תלות במסנני פעולה ב- ASP.NET Core 3.1
  • כיצד להשתמש בתבנית האפשרויות ב- ASP.NET Core
  • כיצד להשתמש בניתוב נקודות קצה ב- ASP.NET Core 3.0 MVC
  • כיצד לייצא נתונים ל- Excel ב- ASP.NET Core 3.0
  • כיצד להשתמש ב- LoggerMessage ב- ASP.NET Core 3.0
  • כיצד לשלוח מיילים ב- ASP.NET Core
  • כיצד לתעד נתונים לשרת SQL ב- ASP.NET Core
  • כיצד לתזמן עבודות באמצעות Quartz.NET ב- ASP.NET Core
  • כיצד להחזיר נתונים מממשק ה- API של ASP.NET Core
  • כיצד לעצב נתוני תגובה ב ASP.NET Core
  • כיצד לצרוך ASP.NET Core API API באמצעות RestSharp
  • כיצד לבצע פעולות סינכרון באמצעות Dapper
  • כיצד להשתמש בדגלי תכונה ב- ASP.NET Core
  • כיצד להשתמש במאפיין FromServices ב- ASP.NET Core
  • כיצד לעבוד עם קובצי Cookie ב- ASP.NET Core
  • כיצד לעבוד עם קבצים סטטיים בליבת ASP.NET
  • כיצד להשתמש ב- Middleware לכתיבת כתובות אתרים בליבת ASP.NET
  • כיצד ליישם הגבלת קצב ב- ASP.NET Core
  • כיצד להשתמש בתובנות יישומי תכלת הרקיע בליבת ASP.NET
  • שימוש בתכונות NLog מתקדמות ב- ASP.NET Core
  • כיצד לטפל בשגיאות ב- ASP.NET Web API
  • כיצד ליישם טיפול חריגים גלובלי ב- ASP.NET Core MVC
  • כיצד לטפל בערכי אפס ב- ASP.NET Core MVC
  • גרסאות מתקדמות ב- ASP.NET Core API
  • כיצד לעבוד עם שירותי עובדים ב- ASP.NET Core
  • כיצד להשתמש ב- API להגנה על נתונים בליבת ASP.NET
  • כיצד להשתמש בתוכנת תיווך מותנית ב- ASP.NET Core
  • כיצד לעבוד עם מצב הפעלה ב- ASP.NET Core
  • כיצד לכתוב בקרים יעילים ב- ASP.NET Core