Vlastní dovednosti webového rozhraní API v kanálu rozšiřování služby Azure AI Vyhledávač

Využijte dovednosti vlastního webového rozhraní API k rozšíření rozšíření AI voláním koncového bodu webového rozhraní API, který poskytuje vlastní operace. Podobně jako integrované dovednosti má dovednost vlastního webového rozhraní API vstupy a výstupy. V závislosti na vstupech obdrží webové rozhraní API datovou část JSON při spuštění indexeru a vrátí datovou část JSON jako odpověď spolu se stavovým kódem úspěchu. Odpověď musí obsahovat výstupy zadané vaší vlastní dovedností. Jakákoli jiná odpověď se považuje za chybu a neprovádí se žádné rozšiřování. Struktura datové části JSON je popsána dále v tomto dokumentu.

Dovednost vlastního webového rozhraní API se používá také při implementaci funkce Azure OpenAI ve vašich datech. Pokud je Azure OpenAI nakonfigurovaný pro přístup na základě role a při vytváření vektorového indexu dojde 403 Forbidden k chybám, ověřte, že Azure AI Vyhledávač má přiřazenou identitu systému a běží jako důvěryhodná služba na Azure OpenAI.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parametry dovedností

Parametry rozlišují malá a velká písmena.

authResourceId Vysvětlení hodnoty

Když dovednost vlastního webového rozhraní API používá ověřování spravované identity, Azure AI Vyhledávač získá přístupový token Microsoft Entra a odešle ho do koncového bodu vlastní dovednosti. Vlastnost authResourceId určuje identifikátor prostředku, označovaný také jako identifikátor cílové skupiny nebo identifikátor URI ID aplikace, pro který je token požadován. Hodnota musí odpovídat tomu, co cílová aplikace očekává během ověřování tokenu. V opačném případě ověřování selže s 401 Unauthorized odpovědí.

Tato authResourceId hodnota identifikuje aplikaci hostující vaši vlastní dovednost. Nejedná se o adresu URL vaší vyhledávací služby ani indexeru.

Následující tabulka uvádí běžné formáty:

Vlastnost přijímá formáty s příponou oboru a bez této přípony .default . Umožňuje api://<appId> přímo spárovat identifikátor URI ID aplikace. Pokud zahrnete příponu .default , například api://<appId>/.defaultdeklaraci identity přístupového tokenu aud , obsahuje identifikátor URI základního ID aplikace bez přípony.

Postup konfigurace ověřování Microsoft Entra pro funkci Azure a nastavení authResourceIdnajdete v tématu Použití spravované identity vyhledávací služby pro připojení k aplikaci funkcí Azure.

Příklad: funkce Azure chráněná službou Microsoft Entra ID

V tomto příkladu Azure AI Vyhledávač získá přístupový token pro cílovou skupinu určenou authResourceId cílovou skupinou a zahrne token při vyvolání koncového bodu vlastní dovednosti.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso-function.azurewebsites.net/api/enrich",
  "authResourceId": "api://contoso-customskill"
}

Vstupy dovedností

Tato dovednost nemá žádné předdefinované vstupy. Vstupy jsou jakékoli existující pole nebo jakýkoli uzel ve stromu rozšiřování, který chcete předat vlastní dovednosti.

Výstupy schopností

Tato dovednost nemá žádné předdefinované výstupy. Pokud se má výstup dovednosti odeslat do pole v indexeru, nezapomeňte v indexu vyhledávání definovat mapování výstupních polí.

Ukázková definice

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso.example.org/api?code=<redacted>",
  "httpMethod": "POST",
  "name": "myCustomSkill",
  "httpHeaders": {
    "Authorization": "<redacted>",
    "Ocp-Apim-Subscription-Key": "<redacted>"
  }
}

{
  "uri": "<unchanged>",
  "httpHeaders": {
    "Authorization": "<unchanged>",
    "Ocp-Apim-Subscription-Key": "<unchanged>"
  }
}

Ukázka vstupní struktury JSON

Tato struktura JSON představuje datovou část, kterou odesíláte do webového rozhraní API. Vždy se řídí těmito omezeními:

• Volá se values entita nejvyšší úrovně a je pole objektů. Počet těchto objektů je nejvýše batchSize.

• Každý objekt v values poli má:

  • Vlastnost recordId , která je jedinečným řetězcem sloužícím k identifikaci daného záznamu.

  • Vlastnost data , která je objektem JSON. Pole data vlastnosti odpovídají "názvům" zadaným v inputs části definice dovednosti. Hodnoty těchto polí pocházejí z source těchto polí (které můžou být z pole v dokumentu nebo potenciálně z jiné dovednosti).

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Ukázková výstupní struktura JSON

Výstup odpovídá odpovědi vrácené z webového rozhraní API. Webové rozhraní API by mělo vrátit pouze datovou část JSON (ověřenou pomocí Content-Type hlavičky odpovědi) a měla by splňovat následující omezení:

• Měla by existovat entita nejvyšší úrovně s názvem values, která by měla být pole objektů.

• Počet objektů v poli by měl být stejný jako počet objektů odesílaných do webového rozhraní API.

• Každý objekt by měl mít:

  • Vlastnost recordId .

  • Vlastnost data , která je objektem, kde pole jsou obohacení odpovídající "názvům" v output a jehož hodnota je považována za obohacení.

  • Vlastnost errors , pole uvádějící všechny chyby, ke kterým došlo při přidání do historie provádění indexeru. Tato vlastnost je povinná, ale může mít null hodnotu.

  • Vlastnost warnings , pole zobrazující všechna upozornění, která byla zjištěna při přidání do historie provádění indexeru. Tato vlastnost je povinná, ale může mít null hodnotu.

• Pořadí objektů v values požadavku nebo odpovědi není důležité. Používá se recordId však pro korelaci, takže se zahodí jakýkoli záznam v odpovědi obsahující záznam recordId, který nebyl součástí původního požadavku webového rozhraní API.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

Chybové případy

Kromě nedostupnosti webového rozhraní API nebo odesílání nespělých stavových kódů zvažte následující případy jako chyby:

• Pokud webové rozhraní API vrátí stavový kód úspěchu, ale odpověď značí, že není application/json, odpověď je neplatná a neprovedou se žádné rozšiřování.

• Pokud pole odpovědi values obsahuje neplatné záznamy (například chybějící nebo duplikované recordId), neplatné záznamy nejsou obohaceny. Při vývoji vlastníchdovednostích Na tento příklad se můžete podívat v úložišti Power Skill, které se řídí očekávaným kontraktem.

V případech, kdy webové rozhraní API není k dispozici nebo vrací chybu HTTP, obsahuje historie spuštění indexeru popisnou chybu se všemi dostupnými podrobnostmi o chybě HTTP.

Aspekty zabezpečení pro ověřování spravovaných identit

Pokud používáte ověřování spravované identity s vlastní dovedností webového rozhraní API, Azure AI Vyhledávač získá přístupový token Microsoft Entra pro aplikaci identifikovanou authResourceId aplikací a zahrne tento token do požadavků odeslaných do koncového bodu určeného urikoncovým bodem . Koncový bod, na který uri odkazuje, je obvykle vaše funkce Azure, Azure App Service, koncový bod Azure API Management nebo jiná Microsoft Entra chráněná aplikace. Zodpovídáte za konfiguraci a údržbu vztahu mezi koncovým bodem a aplikací identifikovanou uživatelem authResourceId.

Bez ohledu na metodu ověřování můžou vstupy vlastních dovedností obsahovat hodnoty z dokumentů poskytnutých zákazníkem nebo hodnot odvozených z těchto dokumentů. Zacházejte se všemi vstupy vlastních dovedností jako nedůvěryhodnými. Azure AI Vyhledávač předá vstupy nakonfigurované v sadě dovedností do vašeho koncového bodu bez interpretace, ověřování nebo omezení jejich obsahu pro vlastní implementaci.

Než je použijete v odchozích požadavcích nebo jiných operacích citlivých na zabezpečení, ověřte a omezte je ve své vlastní dovednosti. Použijte ověřování vstupu, seznamy povolených cílů, adresu URL a ověření názvu hostitele, omezení protokolu a přístup k síti s nejnižšími oprávněními, které umožňují pouze cíle a porty, které dovednost vyžaduje. Další informace najdete v tématu Strategie architektury pro sítě a připojení.

Doporučené postupy zabezpečení

Pokud chcete pomoct se zabezpečením nasazení, postupujte podle těchto postupů:

• uri Nakonfigurujte vlastnost tak, aby odkazovat pouze na důvěryhodné koncové body, které mají přijímat požadavky z Azure AI Vyhledávač.
• NakonfigurujteauthResourceId, aby identifikovala Microsoft Entra aplikaci, u které se očekává přijetí a ověření přístupového tokenu.
• Před zpracováním požadavků se ujistěte, že aplikace, která přijímá požadavky, ověřuje standardní deklarace identity tokenů, včetně cílové skupiny (aud), vystavitele (iss), tenanta (tid) a všech požadovaných rolí nebo oprávnění aplikace.
• Při udělování oprávnění spravované identitě Azure AI Vyhledávač použijte zásadu nejnižšího oprávnění.
• Pravidelně kontrolujte definice dovedností vlastních webových rozhraní API, Microsoft Entra registrace aplikací a přiřazení rolí aplikací a oprávnění udělená Azure AI Vyhledávač spravovaných identit. Zkontrolujte změny konfigurace prostřednictvím zavedených procesů správy změn a kontroly zabezpečení.
• Pravidelně kontrolujte konfigurace koncových bodů pro Azure Functions, App Services, rozhraní API a brány rozhraní API.
• Monitorujte protokoly přihlašování aplikací, události ověřování a protokoly přístupu k rozhraní API pro neočekávanou nebo neoprávněnou aktivitu.
• Odeberte nepoužívané koncové body, oprávnění, registrace aplikací a přiřazení rolí, které už nejsou potřeba.

Omezení přístupu ke konfiguraci sady dovedností

Uživatelé, kteří mohou vytvářet, upravovat nebo spouštět sady dovedností, můžou řídit cílový koncový bod i konfiguraci ověřování používanou dovedností vlastního webového rozhraní API. Omezte tato oprávnění na důvěryhodné správce a při konfiguraci vlastních dovedností s podporou spravované identity postupujte podle standardních procesů správy změn a kontroly zabezpečení.

Viz také

• Definování sady dovedností
• Přidání vlastní dovednosti do kanálu rozšiřování AI
• Příklad: Vytvoření vlastní dovednosti pro rozšiřování AI
• Úložiště Power Skill