Gegevens indexeren uit Azure Table Storage

Artikel
02/22/2024

In dit artikel leert u hoe u een indexeerfunctie configureert waarmee inhoud uit Azure Table Storage wordt geïmporteerd en hoe u deze doorzoekbaar maakt in Azure AI Search. Invoer in de indexeerfunctie zijn uw entiteiten in één tabel. Uitvoer is een zoekindex met doorzoekbare inhoud en metagegevens die zijn opgeslagen in afzonderlijke velden.

Dit artikel is een aanvulling op Een indexeerfunctie maken met informatie die specifiek is voor indexering vanuit Azure Table Storage. Hierbij worden de REST API's gebruikt om een driedelige werkstroom te demonstreren die gebruikelijk is voor alle indexeerfuncties: een gegevensbron maken, een index maken, een indexeerfunctie maken. Gegevensextractie vindt plaats wanneer u de aanvraag Indexeerfunctie maken verzendt.

Vereisten

Azure-tabelopslag
Tabellen met tekst. Als u binaire gegevens hebt, kunt u AI-verrijking overwegen voor afbeeldingsanalyse.
Leesmachtigingen voor Azure Storage. Een 'volledige toegang' verbindingsreeks bevat een sleutel die toegang geeft tot de inhoud, maar als u Azure-rollen gebruikt, moet u ervoor zorgen dat de door de zoekservice beheerde identiteit gegevens- en lezermachtigingen heeft.
Gebruik een REST-client om REST-aanroepen te formuleren die vergelijkbaar zijn met de aanroepen die in dit artikel worden weergegeven.

De gegevensbron definiëren

De definitie van de gegevensbron specificeert de brongegevens voor indexering, referenties en beleidsregels voor wijzigingsdetectie. Een gegevensbron is een onafhankelijke resource die kan worden gebruikt door meerdere indexeerfuncties.

Een gegevensbron maken of bijwerken om de definitie ervan in te stellen:

 POST https://[service name].search.windows.net/datasources?api-version=2023-11-01 
 {
     "name": "my-table-storage-ds",
     "description": null,
     "type": "azuretable",
     "subtype": null,
     "credentials": {
        "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>"
     },
     "container": {
        "name": "my-table-in-azure-storage",
        "query": ""
     },
     "dataChangeDetectionPolicy": null,
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
 }

Stel 'type' in op "azuretable" (vereist).
Stel referenties in op een Azure Storage-verbindingsreeks. In de volgende sectie worden de ondersteunde indelingen beschreven.
Stel 'container' in op de naam van de tabel.
Stel desgewenst 'query' in op een filter op PartitionKey. Het instellen van deze eigenschap is een best practice die de prestaties verbetert. Als 'query' null is, voert de indexeerfunctie een volledige tabelscan uit, wat kan leiden tot slechte prestaties als de tabellen groot zijn.

Een definitie van een gegevensbron kan ook beleid voor voorlopig verwijderen bevatten, als u wilt dat de indexeerfunctie een zoekdocument verwijdert wanneer het brondocument wordt gemarkeerd voor verwijdering.

Ondersteunde referenties en verbindingsreeks s

Indexeerfuncties kunnen verbinding maken met een tabel met behulp van de volgende verbindingen.

Opslagaccount voor volledige toegang verbindingsreeks
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
U kunt de verbindingsreeks ophalen op de pagina Opslagaccount in Azure Portal door toegangssleutels te selecteren in het linkernavigatiedeelvenster. Zorg ervoor dat u een volledige verbindingsreeks en niet alleen een sleutel selecteert.

Beheerde identiteit verbindingsreeks
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Voor deze verbindingsreeks is geen accountsleutel vereist, maar u moet eerder een zoekservice hebben geconfigureerd om verbinding te maken met een beheerde identiteit.

Shared Access Signature** (SAS) voor opslagaccounts verbindingsreeks
`{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }`
De SAS moet de lijst en leesmachtigingen hebben voor tabellen en entiteiten.

Handtekening voor gedeelde toegang voor containers
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
De SAS moet de lijst en leesmachtigingen voor de container hebben. Zie Shared Access Signatures gebruiken voor meer informatie.

Notitie

Als u SAS-referenties gebruikt, moet u de referenties van de gegevensbron periodiek bijwerken met vernieuwde handtekeningen om te voorkomen dat deze verlopen. Wanneer SAS-referenties verlopen, mislukt de indexeerfunctie met een foutbericht dat lijkt op 'Referenties die zijn opgegeven in de verbindingsreeks ongeldig zijn of zijn verlopen'.

Partitie voor verbeterde prestaties

Azure AI Search maakt standaard gebruik van het volgende interne queryfilter om bij te houden welke bronentiteiten zijn bijgewerkt sinds de laatste uitvoering: Timestamp >= HighWaterMarkValue. Omdat Azure-tabellen geen secundaire index in het Timestamp veld hebben, is voor dit type query een volledige tabelscan vereist en is dit dus traag voor grote tabellen.

Als u een volledige scan wilt voorkomen, kunt u tabelpartities gebruiken om het bereik van elke indexeertaak te beperken.

Als uw gegevens op natuurlijke wijze kunnen worden gepartitioneerd in verschillende partitiebereiken, maakt u een gegevensbron en een bijbehorende indexeerfunctie voor elk partitiebereik. Elke indexeerfunctie moet nu alleen een specifiek partitiebereik verwerken, wat resulteert in betere queryprestaties. Als de gegevens die moeten worden geïndexeerd een klein aantal vaste partities hebben, nog beter: elke indexeerfunctie voert alleen een partitiescan uit.

Als u bijvoorbeeld een gegevensbron wilt maken voor het verwerken van een partitiebereik met sleutels van 000 waaruit 100, gebruikt u een query als volgt: "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }
Als uw gegevens op tijd worden gepartitioneerd (bijvoorbeeld als u elke dag of week een nieuwe partitie maakt), kunt u de volgende aanpak overwegen:
- Geef in de definitie van de gegevensbron een query op die vergelijkbaar is met het volgende voorbeeld: (PartitionKey ge <TimeStamp>) and (other filters).
- Bewaak de voortgang van de indexeerfunctie met behulp van de <TimeStamp> Status-API van Get Indexer en werk de voorwaarde van de query periodiek bij op basis van de meest recente geslaagde waarde voor hoge watermarkeringen.
- Als u met deze methode een volledige herindex moet activeren, stelt u de gegevensbronquery opnieuw in naast het opnieuw instellen van de indexeerfunctie.

Zoekvelden toevoegen aan een index

Voeg in een zoekindex velden toe om de inhoud en metagegevens van uw tabelentiteiten te accepteren.

Een index maken of bijwerken om zoekvelden te definiëren waarmee inhoud van entiteiten wordt opgeslagen:

POST https://[service name].search.windows.net/indexes?api-version=2023-11-01 
{
  "name" : "my-search-index",
  "fields": [
    { "name": "Key", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
  ]
}

Maak een documentsleutelveld ('sleutel': true),maar sta de indexeerfunctie toe dat het automatisch wordt ingevuld. Een tabelindexeerfunctie vult het sleutelveld met samengevoegde partitie- en rijsleutels uit de tabel. Als de PartitionKey van een rij bijvoorbeeld is 1 en RowKey is 1_123, is 11_123de sleutelwaarde . Als de partitiesleutel null is, wordt alleen de rijsleutel gebruikt.

Als u de wizard Gegevens importeren gebruikt om de index te maken, wordt in de portal een sleutelveld voor de zoekindex afgeleid en wordt een impliciete veldtoewijzing gebruikt om de bron- en doelvelden te verbinden. U hoeft het veld niet zelf toe te voegen en u hoeft geen veldtoewijzing in te stellen.

Als u de REST API's gebruikt en impliciete veldtoewijzingen wilt, maakt en noemt u het documentsleutelveld Sleutel in de definitie van de zoekindex, zoals wordt weergegeven in de vorige stap ({ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }). De indexeerfunctie vult het sleutelveld automatisch in, zonder dat er veldtoewijzingen vereist zijn.

Als u geen veld met de naam Sleutel in uw zoekindex wilt, voegt u een expliciete veldtoewijzing toe aan de definitie van de indexeerfunctie met de gewenste veldnaam en stelt u het bronveld in op Sleutel:
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Key",
     "targetFieldName" : "MyDocumentKeyFieldName"
   }
]
```
Voeg nu eventuele andere entiteitsvelden toe die u in uw index wilt opnemen. Als een entiteit er bijvoorbeeld uitziet zoals in het volgende voorbeeld, moet uw zoekindex velden bevatten voor HotelName, Description en Category om deze waarden te ontvangen.

Als u dezelfde namen en compatibele gegevenstypen gebruikt, hoeft u geen veldtoewijzingen meer te gebruiken. Wanneer namen en typen hetzelfde zijn, kan de indexeerfunctie het gegevenspad automatisch bepalen.

De tabelindexeerfunctie configureren en uitvoeren

Zodra u een index en gegevensbron hebt, kunt u de indexeerfunctie maken. De configuratie van de indexeerfunctie geeft de invoer, parameters en eigenschappen aan die het gedrag van de uitvoeringstijd regelen.

Maak of werk een indexeerfunctie bij door deze een naam te geven en te verwijzen naar de gegevensbron en doelindex:

POST https://[service name].search.windows.net/indexers?api-version=2023-11-01
{
    "name" : "my-table-indexer",
    "dataSourceName" : "my-table-storage-ds",
    "targetIndexName" : "my-search-index",
    "disabled": null,
    "schedule": null,
    "parameters" : {
        "batchSize" : null,
        "maxFailedItems" : null,
        "maxFailedItemsPerBatch" : null,
        "base64EncodeKeys" : null,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

Geef veldtoewijzingen op als er verschillen zijn in veldnaam of -type, of als u meerdere versies van een bronveld in de zoekindex nodig hebt. Het veld Doel is de naam van het veld in de zoekindex.
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Description",
     "targetFieldName" : "HotelDescription"
   }
]
```
Zie Een indexeerfunctie maken voor meer informatie over andere eigenschappen.

Een indexeerfunctie wordt automatisch uitgevoerd wanneer deze wordt gemaakt. U kunt dit voorkomen door 'uitgeschakeld' in te stellen op waar. Als u de uitvoering van de indexeerfunctie wilt beheren, voert u een indexeerfunctie op aanvraag uit of plaatst u deze in een schema.

De status van de indexeerfunctie controleren

Als u de status en uitvoeringsgeschiedenis van de indexeerfunctie wilt controleren, verzendt u een get-indexeerstatusaanvraag :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
  Content-Type: application/json  
  api-key: [admin key]

Het antwoord bevat de status en het aantal verwerkte items. Het moet er ongeveer uitzien als in het volgende voorbeeld:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2023-02-21T00:23:24.957Z",
            "endTime":"2023-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2023-02-21T00:23:24.957Z",
                "endTime":"2023-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

De uitvoeringsgeschiedenis bevat maximaal 50 van de laatst voltooide uitvoeringen, die in de omgekeerde chronologische volgorde worden gesorteerd, zodat de laatste uitvoering als eerste wordt uitgevoerd.

Volgende stappen

Meer informatie over het uitvoeren van de indexeerfunctie, het bewaken van de status of het plannen van de uitvoering van de indexeerfunctie. De volgende artikelen zijn van toepassing op indexeerfuncties die inhoud ophalen uit Azure Storage: