Criar índice (API REST do Azure AI Search)

Um índice é o principal meio de organizar e pesquisar documentos no Azure AI Search, semelhante a como uma tabela organiza registros em um banco de dados. Cada índice tem uma coleção de documentos que estão em conformidade com o esquema de índice (nomes de campo, tipos de dados e atributos), mas os índices também especificam constructos adicionais (sugestores, perfis de pontuação e configuração cors) que definem outros comportamentos de pesquisa.

Você pode usar POST ou PUT na solicitação. Para qualquer um deles, o documento JSON no corpo da solicitação fornece a definição de objeto.

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

Como alternativa, você pode usar 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]

HTTPS é necessário para todas as solicitações de serviço. Se o índice não existir, ele será criado. Se ele já existir, ele será atualizado para a nova definição.

Criar um índice estabelece o esquema e os metadados. Popular o índice é uma operação separada. Para esta etapa, você pode usar um indexador (consulte Operações do indexador, disponíveis para fontes de dados com suporte) ou adicionar , atualizar ou excluir documentos. Os índices invertidos são gerados quando os documentos são postados.

Parâmetros de URI

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionais

Corpo da solicitação

O corpo da solicitação contém uma definição de esquema, que inclui a lista de campos de dados em documentos que serão inseridos nesse índice.

O JSON a seguir é uma representação de alto nível das partes main 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) { }  
}  

A contém as seguintes propriedades:

Definições de campo

Os atributos a seguir podem ser definidos em um campo ao criar um índice.

Resposta

Para uma solicitação bem-sucedida, você deverá ver o código de status “201 (Criado)”.

Por padrão, o corpo da resposta contém o JSON para a definição de índice. No entanto, se o cabeçalho da Prefer solicitação estiver definido return=minimalcomo , o corpo da resposta estará vazio e o êxito status código será "204 Sem Conteúdo" em vez de "201 Criado". Isso é verdadeiro independentemente de a operação PUT ou POST ser usada 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 sugestor é referenciado por nome em solicitações de consulta que incluem a API de Sugestões ou a API de Preenchimento Automático, dependendo se você deseja retornar uma correspondência ou o restante de um termo de consulta. Para obter mais informações sobre como criar e usar um sugestor, consulte Criar um sugestor.

Exemplo: similaridade para relevância de pesquisa

Essa propriedade define o algoritmo de classificação usado para criar uma pontuaçã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, essa propriedade é ignorada porque o algoritmo de similaridade é sempre BM25. Para serviços existentes criados antes de 15 de julho de 2020, você pode aceitar o BM25 definindo esse constructo da seguinte maneira:

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

Exemplo: opções de CORS

O JavaScript do lado do cliente não pode chamar nenhuma APIs por padrão, pois o navegador impedirá todas as solicitações entre origens. Para permitir consultas entre origens ao índice, habilite o CORS (compartilhamento de recursos entre origens (Wikipédia)) definindo o corsOptions atributo . Por motivos de segurança, apenas APIs de consulta dão suporte para 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 criptografia

As chaves de criptografia são chaves gerenciadas pelo cliente usadas para criptografia adicional. Para obter mais informações, consulte Criptografia usando chaves gerenciadas 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 Pontuação

Um perfil de pontuação é uma seção do esquema que define comportamentos de pontuação personalizados que permitem influenciar quais documentos aparecem mais alto nos resultados da pesquisa. Perfis de pontuação são compostos de funções e pesos de campos. Para usá-las, você pode especificar um perfil por nome na sequência de consulta. Para obter mais informações, consulte Adicionar perfis de pontuaçã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 em seu serviço de pesquisa, você pode atribuí-lo a searchable campos do tipo Edm.String ou Collection(Edm.String) em um índice. A definição de índice abaixo configura o campo "gênero" para usar o mapa de sinônimos 'mysynonymmap'.

Você pode usar Atualizar Índice para adicionar essa propriedade a um campo existente. Uma propriedade synonymMaps de campo especifica o mapa (um por campo). Você pode atualizar as propriedades dos campos existentes a synonymMaps qualquer momento.

Consulte como de costume, usando termos ou frases (entre aspas). No Azure AI Search, termos de duas partes, como "banheira de hidromassagem", devem ser expressos como uma frase, caso contrário, cada termo é avaliado de forma independente. Se você consultar "banheira de hidromassagem", o mecanismo de pesquisa verificará essa frase, bem como quaisquer sinônimos que você definiu, como jacuzzi.

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

Confira também

• Códigos de status HTTP
• Adicionar perfis de pontuação a um índice de pesquisa
• Pesquisar API de documentos
• Tipos de dados com suporte
• Analisadores léxicos