API-administration

Så hvad er det problem, jeg har, der giver mig lyst til at søge efter en API-administrationsløsning? Du har sandsynligvis følgende udfordringer:

• skaleringbruges din API eller API'er af mange klienter i forskellige områder af verden, og du skal sikre, at den er tilgængelig og dynamisk.
• Securityskal du sikre, at din API er sikker, og at det kun er godkendte klienter, der har adgang til den.
• Fejlhåndteringskal du sikre, at din API kan håndtere fejl korrekt.
• Overvågningskal du overvåge dine API'er for at sikre, at de fungerer som forventet.
• Robusthed– du skal sikre, at din API er robust og kan håndtere fejl korrekt.

For hver af disse udfordringer kan du vælge en pointløsning, men det kan være en udfordring at administrere. Overvej også, at dine API'er kan bygges i forskellige tekniske stakke, hvilket betyder, at løsningerne på ovenstående udfordringer kan betyde, at du har brug for forskellige løsninger til hver API. Hvis du har alle disse udfordringer, bør du overveje en central API-administrationsløsning som Azure API Management.

Lad os dykke dybere ned i nogle udfordringer og se, hvordan en central API-administrationsløsning som Azure API Management kan hjælpe dig med at håndtere dem.

Infrastruktur som kode, IaC

Det er helt fint ved at oprette dine Azure-ressourcer ved hjælp af Azure Portal, men i takt med at din infrastruktur vokser, bliver det sværere at administrere. Et af de problemer, du står over for, er, at du ikke nemt kan replikere din infrastruktur i et andet miljø.

Det er også svært at spore alle de ændringer, der er foretaget i din infrastruktur. Denne situation er, hvor Infrastruktur som kode (IaC) kommer ind. IaC er praksis for administration af din infrastruktur ved hjælp af kode. Hvis du vil anvende IaC på Azure, har du flere muligheder, hvoraf den ene er Bicep. Bicep er et DSL (Domain Specific Language) til deklarativ udrulning af Azure-ressourcer. Det er en fantastisk måde at administrere dine cloudressourcer på. Her er et simpelt eksempel på, hvordan Bicep ser ud:

param location string = 'eastus'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: 'mystorageaccount'
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

I det foregående eksempel har vi defineret en lagerkonto ved hjælp af Bicep. Vi har defineret placeringen af lagerkontoen, lagerkontoens type og SKU'en (lagerenhed). Placering er en parameter, som vi kan overføre, når vi installerer Bicep-filen. Hvis du vil udrulle den viste fil, vil vi bruge Kommandolinjegrænsefladen i Azure på følgende måde:

az deployment group create --resource-group myResourceGroup --template-file main.bicep

Den foregående kommando installerer lagerkontoen i ressourcegruppen myResourceGroup og bruger Bicep-filen main.bicep til at oprette ressourcerne i filen.

Håndtering af belastning via en belastningsjustering

Tilføjelse af en konstruktion til justering af belastning er svaret, når problemet er, at din API er overvældet af anmodninger. En belastningsjustering kan hjælpe dig med at distribuere belastningen på tværs af flere forekomster af din API.

I Azure API Management-tjenesten implementeres justering af belastning ved at definere et koncept, der kaldes backends. Ideen er, at du konfigurerer mange backends, der svarer til dine API-slutpunkter, og derefter opretter du en belastningsjustering, der distribuerer belastningen på tværs af disse backends. Sådan ser arkitekturen ud:

Det, der sker i den foregående arkitektur, er:

1. Klienten sender en anmodning til API Management-forekomsten.
2. Anmodningen er godkendt og godkendt.
3. Anmodningen sendes derefter til belastningsjusteringen.
4. Belastningsjusteringen distribuerer anmodningen til en af backends (den valgte Azure OpenAI-API er angivet med fed).

Backend behandler anmodningen og sender et svar tilbage til klienten.

Definition af justering af belastning

Hvis du vil konfigurere en belastningsjustering i Azure API Management, skal du gøre følgende:

• Backends, lige så mange backends, som du vil distribuere belastningen på.
• Belastningsjustering, en belastningsjustering, der indeholder de backends, du vil fordele belastningen på tværs af.
• En politik, der dirigerer de indgående opkald til belastningsjusteringen.

Oprettelse af backends

Hvis du vil oprette en backend i Azure API Management, skal du definere et backend-objekt. Sådan definerer du en backend i Bicep:

resource backend2 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  parent: apimService
  name: 'backend2'
  properties: {
    url: '${openai2Endpoint}openai'
    protocol: 'http'
    circuitBreaker: {
      rules: [
        {
          failureCondition: {
            count: 3
            errorReasons: [
              'Server errors'
            ]
            interval: 'P1D'
            statusCodeRanges: [
              {
                min: 500
                max: 599
              }
            ]
          }
          name: 'myBreakerRule'
          tripDuration: 'PT1H'
        }
      ]
    }
}

I den foregående Bicep-kode er en backend defineret til at svare til en URL-adresse til API-slutpunktet. Bemærk også navnet backend2 dette navn er noget, vi kan bruge senere. For hver backend, du har, skal du kode den på samme måde som den foregående bicep-kode.

Opret backend-pulje

Derefter vil vi oprette en backendgruppe, der konfigurerer, hvilke backends vi vil fordele belastningen mellem. Vi kan kode denne backendgruppe som en backendenhed på følgende måde:

resource loadBalancing 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  parent: apimService
  name: 'LoadBalancer'
  properties: {
    description: 'Load balancer for multiple backends'
    type: 'Pool'
    pool: {
      services: [
        {
          id: '/subscriptions/${subscriptionId}/resourceGroups/${resourceGroupName}/providers/Microsoft.ApiManagement/service/${apimService.name}/backends/${backend1.id}'
        }
        {
          id: '/subscriptions/${subscriptionId}/resourceGroups/${resourceGroupName}/providers/Microsoft.ApiManagement/service/${apimService.name}/backends/${backend2.id}'
        }
      ]
    }
  }
}

Den backend, vi oprettede før, backend2, refereres sammen med en anden backend-backend1, som vi udeladte for korthed.

Vi kan også inkludere en priority og weight egenskab for hvert element på listen services for at bestemme, hvordan belastningsjusteringen fordeler belastningen. Sådan kan du angive prioritet og vægt for hver backend:

services: [
    {
      id: '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-1'
      priority: 1
      weight: 3
    }
    {
      id: '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-2'
      priority: 1
      weight: 1
    }
  ]

I det foregående eksempel distribuerer belastningsjusteringen belastningen til backend-1 tre gange mere end backend-2.

Direkte indgående opkald

Endelig skal vi dirigere alle indgående opkald til denne belastningsjusterings backend. Retningsinstruktionen oprettes følgende API-enhed:

resource api1 'Microsoft.ApiManagement/service/apis@2020-06-01-preview' = {
  parent: apimService
  name: apiName
  properties: {
    displayName: apiName
    apiType: 'http'
    path: apiSuffix
    format: 'openapi+json-link'
    value: 'https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2024-03-01-preview/inference.json'
    subscriptionKeyParameterNames: {
      header: 'api-key'
    }
    
}

Konfigurer politikken

Nu kan vi endelig angive politikken for den tidligere beskrevne API og dirigere de indgående kald til belastningsjusteringen:

// policy.xml
<policies>
  <inbound>
    <base />
    <set-backend-service id="apim-generated-policy" backend-id="{0}" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

var headerPolicyXml = format(loadTextContent('./policy.xml'), loadBalancing.name, 5000)

// Create a policy for the API, using the headerPolicyXml variable
resource apiPolicy 'Microsoft.ApiManagement/service/apis/policies@2020-06-01-preview' = {
  parent: api1
  name: 'policy'
  properties: {
    format: 'rawxml'
    value: headerPolicyXml
  }
}

Det, vi gjorde, var at oprette en politik, der dirigerer de indgående opkald til belastningsjusteringen. Politikken for set-backend-service bruges til at dirigere de indgående opkald til belastningsjusteringen. Egenskaben backend-id er angivet til navnet på den belastningsjustering, vi oprettede før.

Når alle disse bevægelige dele er på plads, er din API Management-forekomst nu belastningsafbalanceret. Du kan nu skalere din API ved at føje flere backends til belastningsjusteringen.

Kredsløbsafbryder

En kredsløbsafbryder er noget, du bruger, når du vil beskytte din API mod at blive overvældet af anmodninger. Den måde, det fungerer på, er, at du definerer et sæt regler, der, når de opfyldes, udløses og stopper med at sende anmodninger til backend. I Azure API Management kan du definere en kredsløbsafbryder ved at konfigurere en backend og definere en regel for kredsløbsafbryder. Sådan gør du:

resource backend2 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
      parent: apimService
      name: 'backend2'
      properties: {
        url: '${openai2Endpoint}openai'
        protocol: 'http'
        circuitBreaker: {
          rules: [
            {
              failureCondition: {
                count: 3
                errorReasons: [
                  'Server errors'
                ]
                interval: 'P1D'
                statusCodeRanges: [
                  {
                    min: 500
                    max: 599
                  }
                ]
              }
              name: 'myBreakerRule'
              tripDuration: 'PT1H'
            }
          ]
        }
       }
     }

I den foregående backenddefinition er der en egenskab failureCondition, der definerer, hvornår kredsløbsafbryderen skal køre. I dette tilfælde rejser kredsløbsafbryderen, hvis der er tre serverfejl på én dag. Egenskaben tripDuration definerer, hvor længe kredsløbsafbryderen skal forblive åben, før den lukkes igen. Det er god praksis at definere en kredsløbsafbryder for hver backend, du har i din API Management-forekomst.

Administreret identitet

Et andet problem, vi gerne vil løse, er sikkerhed. Du vil sikre dig, at din API er sikker, og at det kun er autoriserede klienter, der kan få adgang til den. En måde at sikre din API på er ved hjælp af administreret identitet. Administreret identitet er en måde at godkende din API på i andre Azure-tjenester. I Azure API Management skal du anvende administreret identitet flere steder, nemlig:

• APIM-forekomstniveaukan du aktivere administreret identitet i APIM-forekomsten ved at angive egenskaben identity til SystemAssigned på følgende måde:

  resource apimService 'Microsoft.ApiManagement/service@2023-09-01-preview' = {
      name: name
      location: location
      tags: union(tags, { 'azd-service-name': name })
      sku: {
      name: sku
      capacity: (sku == 'Consumption') ? 0 : ((sku == 'Developer') ? 1 : skuCount)
      }
      properties: {
          publisherEmail: publisherEmail
          publisherName: publisherName
      // Custom properties are not supported for Consumption SKU
      }
      identity: {
          type: 'SystemAssigned'
      }
  }
  

  Denne handling genererer en administreret identitet for APIM-forekomsten, som vi senere kan bruge vores APIM-forekomst til, f.eks. en Azure OpenAI-forekomst.

• API-niveaukan du knytte det til en politik for din API-forekomst. I den pågældende politik kan du tilføje de nødvendige instruktioner for, at administreret identitet fungerer:

  <policies>
    <inbound>
      <base />
      <authentication-managed-identity resource="https://cognitiveservices.azure.com" output-token-variable-name="managed-id-access-token" ignore-error="false" /> 
  
      <set-header name="Authorization" exists-action="override"> 
        <value>@("Bearer " + (string)context.Variables["managed-id-access-token"])</value> 
    </set-header> 
    </inbound>
    <backend>
      <base />
    </backend>
    <outbound>
      <base />
    </outbound>
    <on-error>
      <base />
    </on-error>
  </policies>
  

  Se de foregående kald til authentication-managed-identity, og set-header disse instruktioner skal du sørge for, at der anvendes administreret identitet på API'en.

• backendniveau, og endelig, hvis dine backends peger på Azure OpenAI-forekomster. Vi skal forbinde vores APIM-forekomst med Azure OpenAI-instansen/-forekomsterne. Hvis du vil oprette denne forbindelse, skal du her se Bicep-instruktionen:

  resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
      principalId: principalId
      principalType: "ServicePrincipal"
      roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
  }
  

  Ideen med ovenstående Bicep-instruktion er at oprette en rolletildeling mellem APIM-forekomsten og Azure OpenAI-forekomsten. I dette tilfælde:

  • principalId er id'et fra APIM-forekomsten,
  • roleDefinitionId er den specifikke bruger, i dette tilfælde er det en bruger, der kaldes "Cognitive Services User", en bruger, der har adgang til Azure OpenAI-forekomsten.
  • namesikrer denne egenskab, at rolletildelingen anvendes på det korrekte omfang, som i dette tilfælde er et bestemt abonnement og en bestemt ressourcegruppe. (skal være den samme ressourcegruppe som Azure OpenAI-forekomsten)