Criar Índice (API REST da Pesquisa de IA do Azure)

Um índice é o principal meio de organizar e pesquisar documentos na Pesquisa de IA do Azure, semelhante à forma como uma tabela organiza registos numa base de dados. Cada índice tem uma coleção de documentos em conformidade com o esquema de índice (nomes de campos, tipos de dados e atributos), mas os índices também especificam construções adicionais (sugestores, perfis de classificação e configuração CORS) que definem outros comportamentos de pesquisa.

Pode utilizar POST ou PUT no pedido. Para qualquer um deles, o documento JSON no corpo do pedido fornece a definição do objeto.

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

Em alternativa, pode utilizar PUT e especificar o nome do índice no URI.

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

O HTTPS é necessário para todos os pedidos de serviço. Se o índice não existir, será criado. Se já existir, será atualizado para a nova definição.

A criação de um índice estabelece o esquema e os metadados. Preencher o índice é uma operação separada. Para este passo, pode utilizar um indexador (veja Operações do indexador, disponíveis para origens de dados suportadas) ou Adicionar, Atualizar ou Eliminar Documentos. Os índices invertidos são gerados quando os documentos são publicados.

Parâmetros do URI

Cabeçalhos de Pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Corpo do Pedido

O corpo do pedido contém uma definição de esquema, que inclui a lista de campos de dados dentro de documentos que serão inseridos neste índice.

O seguinte JSON é uma representação de alto nível das partes principais da definição.

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

O pedido contém as seguintes propriedades:

Definições de campo

Os seguintes atributos podem ser definidos num campo ao criar um índice.

Resposta

Para um pedido com êxito, deverá ver o código de estado "201 Criado".

Por predefinição, o corpo da resposta contém o JSON para a definição de índice. No entanto, se o cabeçalho do Prefer pedido estiver definido como return=minimal, o corpo da resposta está vazio e o código de estado de êxito é "204 Sem Conteúdo" em vez de "201 Criado". Isto é verdade independentemente de PUT ou POST ser utilizado para criar o índice.

Exemplos

Exemplo: um esquema de índice

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

Exemplo: Sugestores

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

Um sugeridor é referenciado por nome em pedidos de consulta que incluem a API de Sugestões ou a API de Conclusão Automática, dependendo se pretende devolver uma correspondência ou o resto de um termo de consulta. Para obter mais informações sobre como criar e utilizar um sugeridor, consulte Criar um sugeridor.

Exemplo: Semelhança para a relevância da pesquisa

Esta propriedade define o algoritmo de classificação utilizado para criar uma classificação de relevância nos resultados da pesquisa de uma consulta de pesquisa de texto completo. Nos serviços criados após 15 de julho de 2020, esta propriedade é ignorada porque o algoritmo de semelhança é sempre BM25. Para serviços existentes criados antes de 15 de julho de 2020, pode optar ativamente por participar no BM25 ao definir esta construção da seguinte forma:

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

Exemplo: Opções CORS

O JavaScript do lado do cliente não pode chamar nenhuma APIs por predefinição, uma vez que o browser irá impedir todos os pedidos de origem cruzada. Para permitir consultas entre origens ao índice, ative o CORS (Partilha de recursos de várias origens (Wikipédia)) ao definir o corsOptions atributo. Por motivos de segurança, apenas as APIs de consulta suportam CORS.

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

Exemplo: Chaves de encriptação

As chaves de encriptação são chaves geridas pelo cliente utilizadas para encriptação adicional. Para obter mais informações, veja Encriptação com chaves geridas pelo cliente no 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)"}
      }
} 

Exemplo: Perfis de Classificação

Um perfil de classificação é uma secção do esquema que define comportamentos de classificação personalizados que lhe permitem influenciar os documentos que aparecem mais alto nos resultados da pesquisa. Os perfis de classificação são compostos por pesos e funções de campo. Para utilizá-los, especifique um perfil por nome na cadeia de consulta. Para obter mais informações, veja Adicionar perfis de classificação a um índice de pesquisa para obter detalhes.

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

Exemplo: Mapas de sinónimos

Depois de criar um mapa de sinónimos no seu serviço de pesquisa, pode atribuí-lo a searchable campos do tipo Edm.String ou Collection(Edm.String) num índice. A definição de índice abaixo configura o campo "género" para utilizar o mapa de sinónimos "mysynonymmap".

Pode utilizar o Índice de Atualização para adicionar esta propriedade a um campo existente. Uma propriedade synonymMaps de campo especifica o mapa (um por campo). Pode atualizar as synonymMaps propriedades dos campos existentes em qualquer altura.

Consulte como habitualmente, utilizando termos ou expressões (entre aspas). No Azure AI Search, os termos em duas partes, como "banheira de hidromassagem", têm de ser expressos como uma expressão, caso contrário, cada termo é avaliado de forma independente. Se consultar "banheira de hidromassagem", o motor de busca procurará essa expressão, bem como quaisquer sinónimos que tenha definido, como o jacuzzi.

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

Ver também

• Códigos de estado HTTP
• Adicionar perfis de classificação a um índice de pesquisa
• API de Documentos de Pesquisa
• Tipos de dados suportados
• Analisadores léxicos