Vytvoření indexu (rozhraní REST API služby Azure AI Search)

Index je primárním způsobem uspořádání a vyhledávání dokumentů ve službě Azure AI Search, podobně jako tabulka uspořádá záznamy v databázi. Každý index má kolekci dokumentů, které odpovídají schématu indexu (názvy polí, datové typy a atributy), ale indexy také určují další konstrukce (návrhy, profily bodování a konfigurace CORS), které definují další chování hledání.

Na žádost můžete použít post nebo PUT. U obou z nich dokument JSON v textu požadavku poskytuje definici objektu.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version]  
  Content-Type: application/json
  api-key: [admin key]  

Případně můžete použít PUT a zadat název indexu v identifikátoru URI.

PUT https://[servicename].search.windows.net/indexes/[index name]?api-version=[api-version]
  Content-Type: application/json
  api-key: [admin key]

Https se vyžaduje pro všechny žádosti o služby. Pokud index neexistuje, vytvoří se. Pokud už existuje, aktualizuje se na novou definici.

Vytvoření indexu vytvoří schéma a metadata. Naplnění indexu je samostatná operace. V tomto kroku můžete použít indexer (viz Operace indexeru, které jsou k dispozici pro podporované zdroje dat) nebo přidat, aktualizovat nebo odstranit dokumenty. Invertované indexy se vygenerují při publikování dokumentů.

Parametry identifikátoru URI

Hlavičky požadavku

Následující tabulka popisuje požadované a volitelné hlavičky požadavků.

Text požadavku

Tělo požadavku obsahuje definici schématu, která obsahuje seznam datových polí v dokumentech, které budou do tohoto indexu předány.

Následující kód JSON představuje základní reprezentaci hlavních částí definice.

{  
  "name": (optional on PUT; required on POST) "Name of the index",  
  "fields": [  
    {  
      "name": "name_of_field",  
      "type": "Edm.String | Edm.Int32 | Edm.Int64 | Edm.Double | Edm.Boolean | Edm.DateTimeOffset | Edm.GeographyPoint | Edm.ComplexType | Collection(Edm.String) | Collection(Edm.Int32) | Collection(Edm.Int64) | Collection(Edm.Double) | Collection(Edm.Boolean) | Collection(Edm.DateTimeOffset) | Collection(Edm.GeographyPoint) | Collection(Edm.ComplexType)",  
      "searchable": true (default where applicable) | false (only Edm.String and Collection(Edm.String) fields can be searchable),  
      "filterable": true (default) | false,  
      "sortable": true (default where applicable) | false (Collection(Edm.String) fields cannot be sortable),  
      "facetable": true (default where applicable) | false (Edm.GeographyPoint fields cannot be facetable),  
      "key": true | false (default, only Edm.String fields can be keys, enable on one field only),  
      "retrievable": true (default) | false,  
      "analyzer": "name_of_analyzer_for_search_and_indexing", (only if 'searchAnalyzer' and 'indexAnalyzer' are not set)
      "searchAnalyzer": "name_of_search_analyzer", (only if 'indexAnalyzer' is set and 'analyzer' is not set)
      "indexAnalyzer": "name_of_indexing_analyzer", (only if 'searchAnalyzer' is set and 'analyzer' is not set)
      "synonymMaps": [ "name_of_synonym_map" ] (optional, only one synonym map per field is currently supported),
      "fields" : [ ... ] (optional, a list of sub-fields if this is a field of type Edm.ComplexType or Collection(Edm.ComplexType). Must be null or empty for simple fields.)
    }
  ],
  "similarity": (optional) { },
  "suggesters": (optional) [ ... ],  
  "scoringProfiles": (optional) [ ... ],  
  "analyzers":(optional) [ ... ],
  "charFilters":(optional) [ ... ],
  "tokenizers":(optional) [ ... ],
  "tokenFilters":(optional) [ ... ],
  "defaultScoringProfile": (optional) "Name of a custom scoring profile to use as the default",  
  "corsOptions": (optional) { },
  "encryptionKey":(optional) { }  
}  

Požadavek obsahuje následující vlastnosti:

Definice polí

Při vytváření indexu je možné u pole nastavit následující atributy.

Odpověď

V případě úspěšného požadavku by se měl zobrazit stavový kód 201 Vytvořeno.

Ve výchozím nastavení tělo odpovědi obsahuje JSON pro definici indexu. Pokud je ale hlavička Prefer požadavku nastavená na return=minimal, text odpovědi je prázdný a stavový kód úspěchu je "204 – Žádný obsah" místo "201 Vytvořeno". To platí bez ohledu na to, jestli se k vytvoření indexu používá PUT nebo POST.

Příklady

Příklad: Schéma indexu

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)", 
      "fields": [
          { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
          { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
          { "name": "Type", "type": "Edm.String", "searchable": true },
          { "name": "BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
          { "name": "BedOptions", "type": "Edm.String", "searchable": true },
          { "name": "SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
          { "name": "SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
          { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
        ]
    }
  ],
  "suggesters": [
      { "name": "sg", "searchMode": "analyzingInfixMatching", "sourceFields": ["HotelName"] }
  ],
  "analyzers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
      "name": "tagsAnalyzer",
      "charFilters": [ "html_strip" ],
      "tokenizer": "standard_v2"
    }
  ]
}  

Příklad: Navrhovatelé

 "suggesters": [  
   {  
     "name": "name of suggester",  
     "searchMode": "analyzingInfixMatching",  
     "sourceFields": ["field1", "field2", ...]  
   }  
 ]

Na navrhovatele se u žádostí dotazů, které obsahují rozhraní API pro návrhy , nebo rozhraní API automatického dokončování odkazuje název, podle toho, jestli chcete vrátit shodu nebo zbytek termínu dotazu. Další informace o vytváření a používání navrhovatele najdete v tématu Vytvoření navrhovatele.

Příklad: Podobnost pro relevanci hledání

Tato vlastnost nastaví algoritmus řazení, který se používá k vytvoření skóre relevance ve výsledcích hledání fulltextového vyhledávacího dotazu. Ve službách vytvořených po 15. červenci 2020 se tato vlastnost ignoruje, protože algoritmus podobnosti je vždy BM25. U existujících služeb vytvořených před 15. červencem 2020 se můžete přihlásit k BM25 nastavením tohoto konstruktoru následujícím způsobem:

 "similarity": {
     "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
 }

Příklad: Možnosti CORS

JavaScript na straně klienta nemůže ve výchozím nastavení volat žádná rozhraní API, protože prohlížeč zabrání všem požadavkům z více zdrojů. Pokud chcete povolit dotazy z více zdrojů do indexu, povolte CORS (Sdílení prostředků mezi zdroji (Wikipedie)) nastavením atributu corsOptions . Z bezpečnostních důvodů podporují CORS pouze rozhraní API pro dotazy.

{
   "name": "hotels",  
   "fields": [ omitted for brevity],
   "suggesters": [ omitted for brevity  ],
   "analyzers": [ omitted for brevity ],
   "corsOptions": (optional) {  
       "allowedOrigins": ["*"] | ["https://docs.microsoft.com:80", "https://azure.microsoft.com:80", ...],  
       "maxAgeInSeconds": (optional) max_age_in_seconds (non-negative integer)  
     }
}

Příklad: Šifrovací klíče

Šifrovací klíče jsou klíče spravované zákazníkem, které se používají k dalšímu šifrování. Další informace najdete v tématu Šifrování pomocí klíčů spravovaných zákazníkem v Azure Key Vault.

{
    "name": "hotels",  
    "fields": [ omitted for brevity],
    "suggesters": [ omitted for brevity  ],
    "analyzers": [ omitted for brevity ],
    "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
        "applicationId": "AAD Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified AAD application)"}
      }
} 

Příklad: Profily bodování

Profil bodování je část schématu, která definuje vlastní chování při vyhodnocování, které vám umožní ovlivnit, které dokumenty se ve výsledcích hledání zobrazí výše. Profily bodování se skládají z vah polí a funkcí. Pokud je chcete použít, zadejte profil podle názvu v řetězci dotazu. Další informace najdete v tématu Přidání profilů hodnocení do vyhledávacího indexu , kde najdete podrobnosti.

{
   "name": "hotels",  
   "fields": [ omitted for brevity],
   "suggesters": [ omitted for brevity  ],
   "analyzers": [ omitted for brevity ],
   "scoringProfiles": [  
   {  
     "name": "name of scoring profile",  
     "text": (optional, only applies to searchable fields) {  
       "weights": {  
         "searchable_field_name": relative_weight_value (positive #'s),  
         ...  
       }  
     },  
     "functions": (optional) [  
       {  
         "type": "magnitude | freshness | distance | tag",  
         "boost": # (positive number used as multiplier for raw score != 1),  
         "fieldName": "...",  
         "interpolation": "constant | linear (default) | quadratic | logarithmic",  
         "magnitude": {  
           "boostingRangeStart": #,  
           "boostingRangeEnd": #,  
           "constantBoostBeyondRange": true | false (default)  
         },  
         "freshness": {  
           "boostingDuration": "..." (value representing timespan leading to now over which boosting occurs)  
         },  
         "distance": {  
           "referencePointParameter": "...", (parameter to be passed in queries to use as reference location)  
           "boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)  
         },  
         "tag": {  
           "tagsParameter": "..." (parameter to be passed in queries to specify a list of tags to compare against target fields)  
         }  
       }  
     ],  
     "functionAggregation": (optional, applies only when functions are specified)   
       "sum (default) | average | minimum | maximum | firstMatching"  
       }  
 ]
}

Příklad: Mapy synonym

Po vytvoření mapy synonym ve vyhledávací službě ji můžete přiřadit k searchable polím typu Edm.String nebo Collection(Edm.String) v indexu. Definice indexu níže nakonfiguruje pole "žánr" tak, aby používalo mapu synonym mysynonymmap.

Tuto vlastnost můžete přidat do existujícího pole pomocí indexu aktualizace . Vlastnost synonymMaps pole určuje mapování (jedno pro každé pole). Vlastnosti existujících polí můžete kdykoli aktualizovat synonymMaps .

Dotazování jako obvykle pomocí termínů nebo frází (uzavřených v uvozovkách) Ve službě Azure AI Search musí být dvoudílné termíny, například "vířivka", vyjádřeny jako fráze, jinak se každý termín vyhodnocuje nezávisle. Pokud zadáte dotaz na "vířivka", vyhledávací web vyhledá tuto frázi i všechna synonyma, která jste definovali, například jacuzzi.

POST /indexes?api-version=2020-06-30
{
    "name":"myindex",
    "fields":[
    ...
        {
            "name":"genre",
            "type":"Edm.String",
            "searchable":true,
            "analyzer":"en.lucene",
            "synonymMaps": [
                "mysynonymmap"
            ]
        }
    ]
    ...
}

Viz také

• Stavové kódy HTTP
• Přidání profilů bodování do vyhledávacího indexu
• Rozhraní API pro vyhledávání dokumentů
• Podporované datové typy
• Lexikální analyzátory