Dela via

Implementera versionshanteringsåtgärder

  • Artikel

Anpassade anslutningsprogram för Azure Logic Apps, Microsoft Power Automate eller Microsoft Power Apps måste tillhandahålla en OpenAPI-specifikationsfil. Denna OpenAPI-specifikation definierar enskilda startpunkter som kallas åtgärder. Varje operation har en unik operationId och en unik urlPath kombination HttpVerb .

{
    "/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        },
        "post": {
            "summary": "Insert row",
            "description": "This operation inserts an item.",
            "operationId": "PostItem"
        }
    }
}

Dessa åtgärder kan växa och ändras med tiden när funktioner läggs till eller utvidgas. Vissa ändringar är bara tillägg och bryter inte nödvändigtvis det kontrakt som finns mellan klienter och servrar. Att lägga till nya parametrar, returnera mer data eller tillåta mer flexibla indata kan ingå i den här kategorin.

Många ändringar kan dock faktiskt bryta kontraktet som beskrivs i OpenAPI-specifikationen. Att ta bort parametrar, inte längre stödja vissa indata eller ändra innebörden och beteendet för indata, utdata eller själva åtgärden, faller under kategorin ”icke-bakåtkompatibel ändring”.

För att kunna utveckla ett API på ett säkert sätt är det viktigt att följa ett mönster som kan navigeras av klienter. Det är API:ets ansvar att upprätthålla bakåtkompatibilitet, kommunicera avsikten och definiera attribut för versionshantering. Det är klientens ansvar att antingen visa eller dölja åtgärder som är föråldrade, förfallna eller som kan ha nya versioner tillgängliga. På så sätt kan driften utvidgas och utvecklas över tid utan att orsaka onödig sårbarhet i program som är beroende av dem.

API-anteckning

OpenAPI har inte inbyggt stöd för åtgärdsversionshantering. För att uppnå vårt mål sker mycket av arbetet genom objektet, som tillämpas både på den globala omfattningen och den operativa omfattningen x-ms-api-annotation . Det globala objektet innehåller egenskaper som gäller för API:et som helhet:

{
    "x-ms-api-annotation": {
        "status": "Preview"
    }
}
Egenskap Värden Default Description
status "Preview" "Production" "Preview" Status för API:et som helhet – börjar i Förhandsversion och eskalerar till Produktion när användning och stabilitet kräver det

I det operativa omfånget innehåller det här objektet mer detaljerade egenskaper. Det finns också ytterligare egenskaper utanför objektet som tillämpas och deltar i processen för utveckling av versioner:

{
    "deprecated": true,
    "x-ms-api-annotation": {
        "status": "Production",
        "family": "MyOperation",
        "revision": 2
    }
}
Egenskap Värden Standardvärde Beskrivning
Deprecated null false true false Anger om åtgärden är föråldrad
x-ms- synlighet null "" "Important" "Advanced" "Internal" "" Avsedd synlighet och framträdande plats för den här åtgärden, där null eller "" innebär ett normalt tillstånd
status "Preview" "Production" "Production" Status för åtgärden – detta kan skilja sig från tillståndet för själva API:et, men om det inte anges ärver det från API-statusen på den översta nivån
familj {gemensamt åtgärdsnamn} operationName Namn som tillämpas för varje revidering av den här åtgärden
revision numerisk (1,2,3...) 1 Revidering av den angivna åtgärdsfamiljen
Upphör ISO8601-datum (inget) Valfritt tips för klienten som anger planerat slut på stödet

Inaktuell kan ställas in på när det inte längre är önskvärt för klienter att använda den här åtgärden true . Den här egenskapen finns i specifikationen för OpenAPI fasta fält .

Synlighet är en indikator på den avsedda relativa framträdandet av åtgärden. En "Important" synlighet anger att åtgärden ska vara längst upp i listan och visas på en framträdande plats. En normal synlighet (anges av null eller tom sträng "") är standard och innebär att åtgärden visas i listan, troligen efter de viktiga åtgärderna. En "Advanced" synlighet indikerar att åtgärden kan vara längst ned i listan eller till och med dold från början bakom en expando-kontroll. Avancerade åtgärder kan vara svårare att använda, mindre populära eller mindre användbara. En "Internal" synlighet anger att åtgärden inte ska exponeras för användare och endast bör användas internt. Interna åtgärder är programmässigt användbara och värdefulla, men är inte avsedda för slutanvändare. Interna åtgärder kan också markeras som sådana för att dölja dem från användargränssnitt under föråldrandeprocessen, utan att de faktiskt tas bort från API:et, vilket annars skulle orsaka en icke-bakåtkompatibel ändring.

Status anger stabiliteten för API:et eller åtgärden. "Preview" indikerar att åtgärden eller API:et är nytt och potentiellt oprövat. Förhandsversion är en indikator om att man för produktionssystem ska iaktta försiktighet i fråga om beroenden. När operationen eller API:et har blivit mer etablerat och har bevisat att det uppfyller standarder för tillförlitlighet, framgångsfrekvens och skalbarhet kan det avsiktligt uppgraderas till "Production" status.

Följande måttkrav gäller i allmänhet för åtgärder som söker "Production" status:

  • 80 % slutförandefrekvens under en period på tre veckor
    • definierat som procent av HTTP-svarskoder i 2xx-intervallet
  • 99,9 % varaktig pålitlighet under en period på tre veckor
    • definierat som procent av HTTP-svarskoder i icke-5xx-intervallet (502, 504 och 520 ingår inte i den här beräkningen)

Familj anger relationen mellan åtgärder som konceptuellt sett är samma åtgärd, men som är olika revisioner med potentiellt icke-bakåtkompatibla ändringar mellan dem. Flera åtgärder delar samma familjenamn om de anses vara revisioner av varandra och sekvenseras av sina unika revisionsnummer.

Revision anger den evolutionära ordningen för åtgärden inom familjen av åtgärder. Varje åtgärd inom en familj har en revidering som är ett heltalsindex som anger sekvens. En tom revision kommer att betraktas som revision 1. När nyare revisioner av en åtgärd är tillgängliga bör klienterna visa dem mer framträdande och rekommendera dem mer avsiktligt, men ändå tillåta att du väljer potentiellt äldre revisioner som ännu inte är inaktuella.

Expires är valfritt och anger en potentiell tidsgräns för slutet av livscykeln där support för åtgärden inte längre garanteras. Detta bör endast anges för föråldrade åtgärder och visas för närvarande inte i något gränssnitt.

Åtgärders livslängd

Åtgärder har en förutsägbar livslängd vilket kan visas i exempel.

Startpunkt

Inledningsvis kanske åtgärder inte nödvändigtvis anger något om revisioner. Dessa åtgärder har standardvärden och betraktas därför som revision 1 i ett efternamn som motsvarar . operationId

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        }
    }
}

Detta motsvarar definitionen mer explicit:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
}

Åtgärdsinitiering

De flesta utvecklingar av ett API utgör tillägg av en åtgärd. Det kan exempelvis vara nya metoder och nya revisioner av befintliga metoder. För att på ett säkert sätt initiera en ny revision justerar du OpenAPI-specifikationen på det här sättet:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (V1 - downplayed)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-visibility": "advanced",
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows (V2 - new hotness)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Preview",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

Viktigt

Observera att GetItems V2 har en unik operationId och visas initialt i förhandsgranskningsstatus. Observera också att GetItems v1 nu har avancerad synlighet, så att det inte visas på ett framträdande sätt.

Föråldrade åtgärder

Ibland kan befintliga v1-startpunkter finnas kvar för alltid, om de fortsätter att tillföra värde och det inte finns någon egentlig anledning att avsluta dem. Många v2-startpunkter ersätter dock avsiktligt v1-startpunkten. För att på ett säkert sätt göra detta bör all trafik uppnå en nominell nollpunkt för den ursprungliga åtgärden. När telemetri bekräftar dessa omständigheter kan följande ändring göras:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (deprecated)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": true,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

Viktigt

Observera att GetItems v1 nu är markerat som föråldrat. Det här är den sista övergångsfasen för föråldrade åtgärder. GetItems v2 har nu fullständigt ersatt GetItems v1.

Varför ska jag bry mig om det?

Det finns många skäl att beakta versionshantering för åtgärder. I första hand ser du till att klienter som Azure Logic Apps och Power Automate fortsätter att fungera korrekt när användare integrerar åtgärder för kopplingar i sina dataflöden. Åtgärder ska följa versionshanteringen enligt metoden ovan när:

  • En ny revision av en åtgärd läggs till
  • En befintlig åtgärd lägger till eller tar bort parametrar
  • En befintlig åtgärd ändrar indata eller utdata betydligt

Strikt bedömning

Det kan finnas fall där du kan komma undan utan versionshantering, men du bör vara försiktig när du gör det och göra många tester för att se till att du inte har förbisett gränsfall där användare kan brytas oväntat. Här är några situationer då du kan klara dig utan den:

  • En ny åtgärd läggs till.

    Detta skulle inte specifikt koppla bort befintliga klienter.

  • En ny valfri parameter läggs till i en befintlig åtgärd.

    Detta skulle inte bryta befintliga anrop, men måste övervägas noggrant.

  • Beteendet ändras en aning för en befintlig åtgärd.

    Detta kanske inte avbryter befintliga anropare, baserat på själva ändringen och vad användarna förlitar sig på. Detta är det mest osäkra fallet, eftersom en betydande skillnad i godkännandet av indata, generering av utdata, tidsinställning eller bearbetning kan påverka beteendet för åtgärden på sätt som kan göra det svårt att fastställa risken för ändringen.

Vi rekommenderar alltid att vara försiktig och att du upprepar en revidering när du gör en icke-trivial API-ändring.

Ge feedback

Vi uppskattar feedback på problem med vår anslutningsplattform eller nya funktioner. Om du vill ge feedback går du till Skicka problem eller får hjälp med anslutningsprogram och väljer din feedbacktyp.