Aangepaste web-API-vaardigheid in een Azure AI Zoeken-verrijkingspijplijn

Gebruik de vaardigheid aangepaste web-API om AI-verrijking uit te breiden door een web-API-eindpunt aan te roepen dat aangepaste bewerkingen biedt. Net als ingebouwde vaardigheden heeft een aangepaste web-API-vaardigheid invoer en uitvoer. Afhankelijk van de invoer ontvangt uw web-API een JSON-nettolading wanneer de indexeerfunctie wordt uitgevoerd en wordt een JSON-nettolading geretourneerd als een antwoord, samen met een statuscode voor een geslaagde status. Het antwoord moet de uitvoer bevatten die is opgegeven door uw aangepaste vaardigheid. Elk ander antwoord wordt beschouwd als een fout en er worden geen verrijkingen uitgevoerd. De structuur van de JSON-nettolading wordt verderop in dit document beschreven.

De vaardigheid aangepaste web-API wordt ook gebruikt bij de implementatie van de functie Azure OpenAI op uw gegevens. Als Azure OpenAI is geconfigureerd voor op rollen gebaseerde toegang en u fouten krijgt 403 Forbidden bij het maken van de vectorindex, controleert u of Azure AI Zoeken een door het systeem toegewezen identiteit heeft en wordt uitgevoerd als een vertrouwde service op Azure OpenAI.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Vaardigheidsparameters

Parameters zijn hoofdlettergevoelig.

Inzicht in de authResourceId waarde

Wanneer een aangepaste web-API-vaardigheid gebruikmaakt van verificatie van beheerde identiteiten, verkrijgt Azure AI Zoeken een Microsoft Entra toegangstoken en verzendt deze naar het eindpunt voor aangepaste vaardigheden. De authResourceId eigenschap geeft de resource-id op, ook wel bekend als de URI van de doelgroep of toepassings-id, waarvoor het token wordt aangevraagd. De waarde moet overeenkomen met wat de doeltoepassing verwacht tijdens de tokenvalidatie. Anders mislukt de verificatie met een 401 Unauthorized antwoord.

De authResourceId waarde identificeert de toepassing die als host fungeert voor uw aangepaste vaardigheid. Dit is niet de URL van uw zoekservice of indexeerfunctie.

In de volgende tabel ziet u algemene indelingen:

De eigenschap accepteert indelingen met en zonder het achtervoegsel van het .default bereik. Gebruik api://<appId> dit rechtstreeks om de URI van de toepassings-id te vinden. Als u een .default achtervoegsel opneemt, zoals api://<appId>/.default, bevat de claim van aud het toegangstoken de URI van de basistoepassings-id zonder het achtervoegsel.

Zie authResourceId voor stappen voor het configureren van Microsoft Entra-verificatie voor een Azure-functie en set.

Voorbeeld: Azure Functie beveiligd door Microsoft Entra ID

In dit voorbeeld verkrijgt Azure AI Zoeken een toegangstoken voor de doelgroep die is opgegeven door authResourceId en bevat het token bij het aanroepen van het eindpunt voor aangepaste vaardigheden.

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

Invoer van vaardigheden

Deze vaardigheid heeft geen vooraf gedefinieerde invoer. De invoer is een bestaand veld of een knooppunt in de verrijkingsstructuur die u wilt doorgeven aan uw aangepaste vaardigheid.

Uitvoer van vaardigheden

Deze vaardigheid heeft geen vooraf gedefinieerde uitvoer. Zorg ervoor dat u een toewijzing van uitvoervelden in de indexeerfunctie definieert als de uitvoer van de vaardigheid moet worden verzonden naar een veld in de zoekindex.

Voorbeelddefinitie

{
  "@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"
    }
  ]
}

Updates voor URI-redaction en referentiebehoud

Dit URI-querygedrag is van toepassing op alle API-versies.

Wanneer u een vaardighedenset met GET- of lijstvaardighedensets met LIST ophaalt, Azure AI Zoeken gevoelige URI-waarden voor aangepaste web-API-vaardigheden (WebApiSkill) redacteert, inclusief sig en , en codeHTTP-headerwaarden. Met deze redacted waarden worden sas-handtekeningen (Shared Access Signature), functiesleutels en headerreferenties beschermd.

Als u opgeslagen geheimen wilt behouden, werkt u dezelfde bestaande resource en hetzelfde eindpunt bij. Verzend de geretourneerde <redacted> of <unchanged> tijdelijke aanduidingen in de PUT-beheeraanvraag. Met deze PUT wordt de definitie van de vaardighedenset bijgewerkt; het is niet de eindpuntaanroep die wordt beheerd door de vaardigheid httpMethod. U kunt het geheel uri ook instellen om <unchanged> de opgeslagen URI te behouden.

Geheime waarden worden niet naar een ander eindpunt overgedragen of gekopieerd naar een nieuwe resource. Voor het wijzigen van een eindpunt, het klonen van een redacted definitie of het op een andere manier opnieuw aanwijzen van een resource, zijn expliciete geheimen vereist.

Als de service geen eenduidige bestaande bron voor een tijdelijke aanduiding kan identificeren, mislukt de PUT met 400 Bad Request en vraagt de werkelijke geheime waarde aan. Een niet-opgeloste of persistente tijdelijke aanduiding is geen bruikbare referentie. Geheimherstel is atomisch: een mislukte herstelbewerking past niet gedeeltelijk URI- of headerwijzigingen toe.

U kunt op elk gewenst moment vervangende URI- of headergeheimen opgeven. Expliciete waarden hebben voorrang op tijdelijke aanduidingen.

Updates voor URI-query's volgen deze regels:

• Voor een Azure-functieparameter code kunt u andere niet-geheime queryparameters bijwerken terwijl u de opgeslagen functiesleutel voor hetzelfde eindpunt behoudt.
• Voor een SAS-parameter sig is de handtekening gebonden aan de omringende niet-geheime queryconfiguratie. Geef een nieuwe handtekening op als het bereik, de machtigingen, het verloop, de resource, de versie, de volgorde, de behuizing of de coderingswijzigingen zijn gewijzigd. Voor zelfs semantisch equivalente opnieuw gerangschikte of opnieuw gecodeerde querytekst is een nieuwe handtekening vereist.

Namen van geheime queryparameters worden niet hoofdlettergevoelig herkend en wanneer het percentage is gecodeerd. De service behoudt uw URI-weergave in plaats van deze te normaliseren. Herhaalde geheime parameters worden vergeleken met exemplaren. Als het exemplaarpatroon niet meer overeenkomt met de opgeslagen URI, geeft u werkelijke waarden op.

Bestaande GET-then-PUT-werkstromen die worden <redacted> gebruikt of <unchanged> ondersteund blijven.

Zie aangepaste web-API-vectorizer-URI-bewerkingen en updates met referentiebehoud voor querytijdvectorisatie.

Met het volgende GET-antwoord worden de functiesleutel- en headerwaarden bewerkt. Als u deze waarden wilt behouden, werkt u dezelfde vaardigheid en hetzelfde eindpunt bij.

{
  "@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>"
  }
}

Als u de hele URI en de bestaande headerwaarden wilt behouden, gebruikt u <unchanged>:

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

Zie Vaardigheidsparameters voor meer informatie over parameters.

JSON-voorbeeldinvoerstructuur

Deze JSON-structuur vertegenwoordigt de nettolading die u naar uw web-API verzendt. Het volgt altijd deze beperkingen:

• De entiteit op het hoogste niveau wordt aangeroepen values en is een matrix met objecten. Het aantal van deze objecten is ten hoogste het batchSizeaantal .

• Elk object in de values matrix heeft:

  • Een recordId eigenschap die een unieke tekenreeks is die wordt gebruikt om die record te identificeren.

  • Een data eigenschap die een JSON-object is. De velden van de data eigenschap komen overeen met de namen die zijn opgegeven in de inputs sectie van de vaardigheidsdefinitie. De waarden van deze velden zijn afkomstig van de source velden (die afkomstig kunnen zijn van een veld in het document of mogelijk van een andere vaardigheid).

{
    "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": []
           }
      }
    ]
}

JSON-voorbeelduitvoerstructuur

De 'uitvoer' komt overeen met het antwoord dat wordt geretourneerd door uw web-API. De web-API mag alleen een JSON-nettolading retourneren (geverifieerd door de Content-Type antwoordheader te bekijken) en moet voldoen aan de volgende beperkingen:

• Er moet een entiteit op het hoogste niveau zijn aangeroepen values. Dit moet een matrix van objecten zijn.

• Het aantal objecten in de matrix moet hetzelfde zijn als het aantal objecten dat naar de web-API wordt verzonden.

• Elk object moet het volgende hebben:

  • Een recordId eigenschap.

  • Een data eigenschap, een object waarbij de velden verrijkingen zijn die overeenkomen met de 'namen' in de output en waarvan de waarde wordt beschouwd als de verrijking.

  • Een errors eigenschap, een matrix met eventuele fouten die zijn opgetreden in de uitvoeringsgeschiedenis van de indexeerfunctie. Deze eigenschap is vereist, maar kan een null waarde hebben.

  • Een warnings eigenschap, een matrix met waarschuwingen die zijn aangetroffen in de uitvoeringsgeschiedenis van de indexeerfunctie. Deze eigenschap is vereist, maar kan een null waarde hebben.

• De volgorde van objecten in de values aanvraag of het antwoord is niet belangrijk. Het recordId wordt echter gebruikt voor correlatie, zodat alle records in het antwoord met een recordId, die geen deel uitmaakten van de oorspronkelijke aanvraag voor de web-API, worden verwijderd.

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

Foutgevallen

Naast dat uw web-API niet beschikbaar is of niet-geslaagde statuscodes verzendt, kunt u rekening houden met de volgende gevallen als fouten:

• Als de web-API een geslaagde statuscode retourneert, maar het antwoord aangeeft dat dit niet application/jsonhet is, is het antwoord ongeldig en worden er geen verrijkingen uitgevoerd.

• Als de antwoordmatrix values ongeldige records bevat (bijvoorbeeld ontbrekend of gedupliceerd recordId), worden de ongeldige records niet verrijkt. Bij het ontwikkelen van aangepaste vaardigheden moet u zich houden aan het vaardigheidscontract voor web-API's. U kunt dit voorbeeld raadplegen in de opslagplaats voor Power Skill die volgt op het verwachte contract.

Voor gevallen waarin de web-API niet beschikbaar is of een HTTP-fout retourneert, bevat de uitvoeringsgeschiedenis van de indexeerfunctie een beschrijvende fout met alle beschikbare details over de HTTP-fout.

Beveiligingsoverwegingen voor verificatie van beheerde identiteiten

Wanneer u verificatie van beheerde identiteit gebruikt met een vaardigheid aangepaste web-API, verkrijgt Azure AI Zoeken een Microsoft Entra toegangstoken voor de toepassing die door authResourceId de toepassing is geïdentificeerd en dat token bevat in aanvragen die worden verzonden naar het eindpunt dat is opgegeven dooruri. Het eindpunt waarnaar uri wordt verwezen, is doorgaans uw Azure Functie, Azure App Service, Azure API Management-eindpunt of een andere Microsoft Entra beveiligde toepassing. U bent verantwoordelijk voor het configureren en onderhouden van de relatie tussen het eindpunt en de toepassing die is geïdentificeerd door authResourceId.

Ongeacht de verificatiemethode kunnen aangepaste vaardigheidsinvoer waarden bevatten uit door de klant geleverde documenten of waarden die zijn afgeleid van deze documenten. Behandel alle aangepaste vaardigheidsinvoeren als niet-vertrouwd. Azure AI Zoeken de invoer die in de vaardighedenset is geconfigureerd, doorstuurt naar uw eindpunt zonder de inhoud ervan te interpreteren, valideren of beperken voor uw aangepaste implementatie.

Valideer en beperk documentgebaseerde waarden in uw aangepaste vaardigheid voordat u deze gebruikt in uitgaande aanvragen of andere beveiligingsgevoelige bewerkingen. Gebruik invoervalidatie, doel-allowlists, URL- en hostnaamvalidatie, protocolbeperkingen en netwerktoegang met minimale bevoegdheden die alleen de bestemmingen en poorten toestaan die de vaardigheid vereist. Zie Architectuurstrategieën voor netwerken en connectiviteit voor meer informatie.

Aanbevolen beveiligingsprocedures

Volg deze procedures om een veilige implementatie te onderhouden:

• Configureer de uri eigenschap zodat deze alleen verwijst naar vertrouwde eindpunten die zijn bedoeld voor het ontvangen van aanvragen van Azure AI Zoeken.
• Configureer authResourceId deze om de Microsoft Entra toepassing te identificeren die naar verwachting het toegangstoken ontvangt en valideert.
• Zorg ervoor dat de toepassing die aanvragen ontvangt, standaardtokenclaims valideert, inclusief doelgroep (aud), uitgever (iss), tenant (tid) en eventuele vereiste toepassingsrollen of machtigingen voordat aanvragen worden verwerkt.
• Pas het principe van minimale bevoegdheden toe bij het verlenen van machtigingen aan de Azure AI Zoeken beheerde identiteit.
• Controleer regelmatig definities van aangepaste web-API-vaardigheden, Microsoft Entra toepassingsregistraties en app-roltoewijzingen en machtigingen die zijn verleend aan Azure AI Zoeken beheerde identiteiten. Controleer configuratiewijzigingen via de bestaande processen voor wijzigingsbeheer en beveiligingsbeoordeling.
• Controleer regelmatig eindpuntconfiguraties voor Azure Functions, App Services, API's en API-gateways.
• Bewaak aanmeldingslogboeken van toepassingen, verificatiegebeurtenissen en API-toegangslogboeken voor onverwachte of niet-geautoriseerde activiteiten.
• Verwijder ongebruikte eindpunten, machtigingen, toepassingsregistraties en roltoewijzingen die niet meer nodig zijn.

Toegang tot de configuratie van vaardighedensets beperken

Gebruikers die vaardighedensets kunnen maken, wijzigen of uitvoeren, kunnen zowel het doeleindpunt als de verificatieconfiguratie beheren die wordt gebruikt door een aangepaste web-API-vaardigheid. Beperk deze machtigingen voor vertrouwde beheerders en volg uw standaardprocessen voor wijzigingsbeheer en beveiligingsbeoordeling bij het configureren van aangepaste vaardigheden voor beheerde identiteiten.

Zie ook

• Een vaardighedenset definiëren
• Aangepaste vaardigheid toevoegen aan een AI-verrijkingspijplijn
• Voorbeeld: Een aangepaste vaardigheid maken voor AI-verrijking
• Power Skill-opslagplaats