API Management

Jaký je problém, kvůli kterému chci vyhledat řešení služby API Management? S největší pravděpodobností máte následující výzvy:

• Škálování, vaše rozhraní API či několik rozhraní API je používáno mnoha klienty v různých částech světa a potřebujete zajistit, aby bylo dostupné a rychle reagující.
• Zabezpečení, musíte zajistit, aby vaše rozhraní API bylo zabezpečené a aby k němu měli přístup jenom autorizovaní klienti.
• Správa chyb vyžaduje, abyste zajistili, že vaše rozhraní API dokáže řádně zpracovat chyby.
• Monitorování vyžaduje monitorování rozhraní API, abyste měli jistotu, že funguje podle očekávání.
• Odolnost je potřeba zajistit, aby vaše rozhraní API bylo odolné a bylo možné řádně zpracovat selhání.

Pro každou z těchto výzev byste se mohli rozhodnout pro bodové řešení, ale to by mohlo být náročné na správu. Zvažte také, že vaše rozhraní API by mohla být sestavená v různých technických zásobníkech, což znamená, že řešení výše uvedených problémů můžou znamenat, že pro každé rozhraní API potřebujete různá řešení. Pokud máte všechny tyto problémy, měli byste zvážit centralizované řešení správy rozhraní API, jako je Azure API Management.

Pojďme se podrobněji podívat na některé problémy a podívat se, jak vám může pomoct řešení centralizované správy rozhraní API, jako je Azure API Management.

Infrastruktura jako kód, IaC

Vytvoření prostředků Azure pomocí webu Azure Portal je naprosto v pořádku, ale s rostoucí infrastrukturou je obtížnější spravovat. Jedním z problémů, kterým čelíte, je, že nemůžete snadno replikovat infrastrukturu v jiném prostředí.

Je také obtížné sledovat všechny změny provedené ve vaší infrastruktuře. V této situaci přichází infrastruktura jako kód (IaC). IaC je postup správy infrastruktury pomocí kódu. Pokud chcete použít IaC v Azure, máte několik možností, z nichž jeden je Bicep. Bicep je jazyk DSL (Domain Specific Language) pro nasazení prostředků Azure deklarativním způsobem. Je to skvělý způsob, jak spravovat cloudové prostředky. Tady je jednoduchý příklad toho, jak Bicep vypadá:

param location string = 'eastus'

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

V předchozím příkladu jsme definovali účet úložiště pomocí Bicep. Definovali jsme umístění účtu úložiště, druh účtu úložiště a skladovou položku (skladovou jednotku). Umístění je parametr, který můžeme předat při nasazení souboru Bicep. K nasazení zobrazeného souboru bychom použili Azure CLI takto:

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

Předchozí příkaz nasadí účet úložiště do skupiny myResourceGroup prostředků a použije soubor main.bicep Bicep k vytvoření prostředků v souboru.

Zpracování zatížení pomocí nástroje pro vyrovnávání zatížení

Přidání konstruktoru vyrovnávání zatížení je odpovědí, když je problém, že vaše rozhraní API je zahlceno požadavky. Nástroj pro vyrovnávání zatížení vám může pomoct distribuovat zatížení napříč několika instancemi vašeho rozhraní API.

Ve službě Azure API Management se vyrovnávání zatížení implementuje definováním konceptu označovaného jako back-endy. Cílem je nastavit mnoho back-endů, které odpovídají vašim koncovým bodům rozhraní API, a pak vytvoříte nástroj pro vyrovnávání zatížení, který distribuuje zatížení mezi tyto back-endy. Takto vypadá architektura:

Co se děje v předchozí architektuře:

1. Klient odešle požadavek do instance služby API Management.
2. Požadavek je ověřený a autorizovaný.
3. Požadavek se pak odešle do nástroje pro vyrovnávání zatížení.
4. Nástroj pro vyrovnávání zatížení distribuuje požadavek do jednoho z back-endů (vybrané rozhraní API Azure OpenAI je označené tučně).

Back-end zpracuje požadavek a odešle odpověď zpět klientovi.

Definování nástroje pro vyrovnávání zatížení

Pokud chcete nastavit nástroj pro vyrovnávání zatížení ve službě Azure API Management, musíte provést následující části:

• Backendy, tolik backendů, kolik potřebujete k rozložení zátěže.
• Nástroj pro vyrovnávání zatížení, nástroj pro vyrovnávání zatížení, který obsahuje back-endy, mezi které chcete zatížení distribuovat.
• Zásada , která směruje příchozí volání do nástroje pro vyrovnávání zatížení.

Vytvoření back-endů

Pokud chcete vytvořit back-end ve službě Azure API Management, musíte definovat entitu back-endu. Tady je postup, jak v Bicep definovat back-end:

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'
        }
      ]
    }
}

V předchozím kódu Bicep je back-end definovaný tak, aby odpovídal adrese URL koncového bodu rozhraní API, všimněte si také názvu backend2 , který můžeme použít později. Pro každý back-end, který máte, byste ho měli zakódovat jako předchozí kód bicep.

Vytvoření back-endového fondu

Dále chceme vytvořit back-endový fond, který nastaví back-endy, mezi které chceme distribuovat zatížení. Tento back-endový fond můžeme zakódovat jako entitu back-endu, například takto:

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}'
        }
      ]
    }
  }
}

Back-end, který jsme vytvořili dříve, backend2se odkazuje společně s jiným back-endem backend1, druhý, který jsme vynechali pro stručnost.

Můžeme také zahrnout a priorityweight vlastnost pro každou položku v services seznamu, abychom zjistili, jak nástroj pro vyrovnávání zatížení distribuuje zatížení. Tady je postup, jak nastavit prioritu a váhu pro každý back-end:

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
    }
  ]

V předchozím příkladu nástroj pro vyrovnávání zatížení distribuuje zatížení třikrát backend-1 více než backend-2.

Přímé příchozí hovory

Nakonec musíme všechny příchozí hovory směrovat na tento back-end vyrovnávání zatížení. Instrukce směru je vytvořena následující entita rozhraní API:

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'
    }
    
}

Konfigurace zásad

Nakonec můžeme nastavit zásady pro dříve popsané rozhraní API a směrovat příchozí volání do nástroje pro vyrovnávání zatížení:

// 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
  }
}

To, co jsme udělali, bylo vytvořit zásadu, která směruje příchozí volání do nástroje pro vyrovnávání zatížení. Zásada set-backend-service slouží k směrování příchozích volání do nástroje pro vyrovnávání zatížení. Vlastnost backend-id je nastavena na název nástroje pro vyrovnávání zatížení, který jsme vytvořili dříve.

Se všemi těmito pohyblivými částmi je teď instance služby API Management vyrovnána zatížení. Teď můžete škálovat rozhraní API přidáním dalších back-endů do nástroje pro vyrovnávání zatížení.

Jistič

Jistič je něco, co používáte, když chcete rozhraní API chránit před zahlcením požadavky. Jak to funguje, definujete sadu pravidel, která po splnění aktivuje jistič a přestane odesílat požadavky do back-endu. Ve službě Azure API Management můžete definovat jistič nastavením back-endu a definováním pravidla jističe. Tady je postup, jak to udělat:

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'
            }
          ]
        }
       }
     }

V předchozí definici back-endu je vlastnost failureCondition , která definuje, kdy má jistič postupovat. V takovém případě dojde k přerušení okruhu, pokud za den dojde ke třem chybám serveru. Vlastnost tripDuration definuje, jak dlouho má jistič zůstat otevřený, než se znovu zavře. Doporučujeme definovat jistič pro každý back-end, který máte v instanci služby API Management.

Spravovaná identita

Dalším problémem, který chceme vyřešit, je zabezpečení. Chcete zajistit, aby vaše rozhraní API bylo zabezpečené a aby k němu měli přístup jenom autorizovaní klienti. Způsob, jak zabezpečit rozhraní API, je použití spravované identity. Spravovaná identita je způsob, jak ověřit vaše rozhraní API v jiných službách Azure. Ve službě Azure API Management je potřeba použít spravovanou identitu na několika místech:

• Úroveň instance APIM, spravovanou identitu v instanci APIM můžete povolit nastavením vlastnosti identity na SystemAssigned takto:

  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'
      }
  }
  

  Tato akce vygeneruje spravovanou identitu pro instanci APIM, kterou můžeme později použít k instanci APIM, například instanci Azure OpenAI.

• Úroveň rozhraní API, pro vaši instanci rozhraní API lze přidružit k určité zásadě. V uvedených zásadách můžete přidat potřebné pokyny pro fungování spravované identity:

  <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>
  

  Podívejte se na authentication-managed-identity předchozí volání a set-header tyto pokyny se ujistěte, že se spravovaná identita používá pro rozhraní API.

• Back-endová úroveň, konečně, za předpokladu, že vaše back-endy odkazují na instance Azure OpenAI. Potřebujeme připojit naši instanci APIM k instanci Azure OpenAI nebo s. Pokud chcete toto připojení provést, tady je instrukce Bicep:

  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)
    }
  }
  

  Výše uvedená instrukce Bicep spočívá v vytvoření přiřazení role mezi instancí APIM a instancí Azure OpenAI. V tomto případě:

  • principalId je ID identity z instance APIM.
  • roleDefinitionId je konkrétní uživatel, v tomto případě se jedná o uživatele s názvem "Uživatel služeb Cognitive Services", který má přístup k instanci Azure OpenAI.
  • name, tato vlastnost zajišťuje, že přiřazení role se použije na správný obor, což je v tomto případě konkrétní předplatné a skupina prostředků. (musí být stejná skupina prostředků jako instance Azure OpenAI).