インデックスの作成または更新 (プレビュー REST API)

: 2023-07-01-Preview に適用されます。 このバージョンはサポートされなくなりました。 新しいバージョンにすぐに アップグレードします。

インデックス では、フィールド コレクション (フィールド名、データ型、属性) だけでなく、他の検索動作を定義する他のコンストラクト (suggesters、スコアリング プロファイル、CORS 構成) も含めて、インデックス スキーマを指定します。

作成要求で POST または PUT を使用できます。 どちらの場合も、要求本文はオブジェクト定義を提供します。

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

更新要求の場合は、PUT を使用し、URI にインデックス名を指定します。

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

すべてのサービス要求には HTTPS が必要です。 インデックスが存在しない場合は作成されます。 既に存在する場合は、新しい定義に更新されます。

インデックス を作成すると、スキーマとメタデータが確立されます。 インデックスの設定は別の操作です。 この手順では、インデクサー (サポートされているデータ ソースで使用できるインデクサー操作のを参照) または ドキュメントの追加、更新、または削除を使用できます。 作成できるインデックスの最大数は、価格レベルによって異なります。 各インデックス内には、個々の要素に制限があります。 詳細については、「Azure AI Searchのサービス制限」を参照してください。

既存のインデックス を更新するには、保持する元の定義を含む完全なスキーマ定義を含める必要があります。 一般に、更新の最適なパターンは、GET を使用してインデックス定義を取得し、変更してから PUT で更新することです。

既存のインデックスにはコンテンツが含まれているため、多くのインデックスを変更するには、インデックスの削除と再構築が必要です。 次のスキーマ変更は、この規則の例外です。

• 新しいフィールドの追加

• スコアリング プロファイル 追加または変更する

• セマンティック構成 追加または変更する

• CORS オプションの変更

• 次の 3 つの変更のいずれかで既存のフィールドを変更します。

  • フィールドの表示/非表示 (retrievable: true | false)
  • クエリ時に使用するアナライザーを変更する (searchAnalyzer)
  • クエリ時に使用される synonymMap を追加または編集します (synonymMaps)

既存のインデックスに対して上記のスキーマ変更を行うには、要求 URI でインデックスの名前を指定し、新しい要素または変更された要素を含む完全に指定されたインデックス定義を含めます。

新しいフィールドが追加されると、インデックス内のすべての既存のドキュメントに、そのフィールドの null 値が自動的に設定されます。 新しいフィールド (マージを使用して) に値が指定されるか、新しいドキュメントが追加されるまで、追加のストレージ領域は使用されません。

suggester の更新には同様の制約があります。新しいフィールドは、フィールドの追加と同時に suggester に追加できますが、既存のフィールドはインデックスの再構築なしで suggesters から削除したり、suggesters に追加したりすることはできません。

アナライザー、トークナイザー、トークン フィルター、または文字フィルター への更新は許可されません。 必要な変更で新しいものを作成できますが、新しいアナライザー定義を追加するときは、インデックスをオフラインにする必要があります。 インデックスの更新要求で allowIndexDowntime フラグを true に設定すると、インデックスがオフラインになります。

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

この操作では、インデックスが少なくとも数秒オフラインになります。つまり、インデックスがオンラインに戻り、要求を処理する準備ができるまで、インデックス作成とクエリ要求は失敗します。

URI パラメーター

要求ヘッダー

次の表では、必須の要求ヘッダーと省略可能な要求ヘッダーについて説明します。

要求本文

要求の本文にはスキーマ定義が含まれています。この定義には、このインデックスにフィードされるドキュメント内のデータ フィールドの一覧が含まれます。

次の JSON は、ベクター検索をサポートするスキーマの大まかな表現です。 スキーマにはキー フィールドが必要であり、そのキー フィールドは検索可能、フィルター可能、並べ替え可能、ファセット可能にすることができます。

ベクトル検索フィールドは、Collection(Edm.Single)型です。 ベクター フィールドはテキスト形式ではないので、ベクター フィールドをキーとして使用することはできません。また、アナライザー、ノーマライザー、サジェスター、またはシノニムを受け入れることはできません。 "dimensions" プロパティと "vectorSearchConfiguration" プロパティが必要です。

ベクター検索をサポートするスキーマでは、キーワード検索もサポートできます。 インデックス内の他の非ベクトル フィールドでは、インデックスに含めるアナライザー、シノニム、スコアリング プロファイルを使用できます。

{  
  "name": (optional on PUT; required on POST) "Name of the index",
  "description": (optional) "Description 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.Single) | Collection(Edm.Double) | Collection(Edm.Boolean) | Collection(Edm.DateTimeOffset) | Collection(Edm.GeographyPoint) | Collection(Edm.ComplexType)",
      "key": true | false (default, only Edm.String fields can be keys, enable on one field only),  
      "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),  
      "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)
      "normalizer": "name_of_normalizer", (optional, applies only to filterable, facetable, or sortable Edm.String and Collection(Edm.String) fields.)
      "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.)
      "dimensions": 1234, (required for vector field definitions. Prohibited for non-vector fields. Integer specifying the dimensionality of the embeddings generated by a machine learning model)
      "vectorSearchConfiguration": "name_of_algorithm_config" (required for vector field definitions. Prohibited for non-vector fields. This should reference an algorithm configuration.)
    }
  ],
  "similarity": (optional) { },
  "suggesters": (optional) [ ... ],  
  "scoringProfiles": (optional) [ ... ],  
  "semantic": (optional) { },
  "vectorSearch": (optional) {
    "algorithmConfigurations": [
        {
            "name": "name_of_algorithm_config",
            "kind": "hnsw" (algorithm type. Only "hnsw" is supported currently.),
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]},
  "normalizers":(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) { }  
}  

要求には、次のプロパティが含まれています。

応答

作成要求が成功すると、状態コード "201 Created" が表示されます。 既定では、応答本文には、作成されたインデックス定義の JSON が含まれます。 ただし、Prefer 要求ヘッダーが return=minimal に設定されている場合、応答本文は空で、成功状態コードは "201 Created" ではなく "204 No Content" になります。 これは、インデックスの作成に PUT と POST のどちらを使用するかに関係なく当てはまります。

更新要求が成功した場合は、"204 No Content" と表示されます。 既定では、応答本文は空です。 ただし、Prefer 要求ヘッダーが return=representationに設定されている場合、応答本文には、更新されたインデックス定義の JSON が含まれます。 この場合、成功状態コードは "200 OK" です。

例

例: ベクター

ベクター検索はフィールド レベルで実装されます。 この定義は、ベクトル フィールドにフォーカスを置きます。 ベクター フィールドは、単精度浮動小数点値の格納に使用 Collection(Edm.Single) 型である必要があります。 ベクター フィールドには、埋め込みの生成に使用される機械学習モデルでサポートされる出力ディメンションの数を保持する "dimensions" プロパティがあります。 たとえば、text-embedding-ada-002 を使用している場合、このドキュメント出力ディメンションの最大数は 1536 です。 "algorithmConfiguration" は、インデックス内の "vectorSearch" 構成の名前に設定されます。 インデックスに複数を定義し、フィールドごとに 1 つを指定できます。

多くの属性は、非ベクトル フィールドにのみ適用されます。 ベクター フィールドでは、"filterable"、"sortable"、"facetable"、"analyzer"、"normalizer"、"synonymMaps" などの属性は無視されます。 同様に、英数字コンテンツを含むフィールドに "dimensions" や "vectorSearchConfiguration" などのベクターのみのプロパティを設定した場合、それらの属性は無視されます。

{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "searchable": true,
            "retrievable": true,
            "filterable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "key": false,
            "searchable": true,
            "retrievable": true,
            "filterable": false,  
            "sortable": false,  
            "facetable": false,
            "analyzer": "",
            "searchAnalyzer": "",
            "indexAnalyzer": "",
            "normalizer": "",
            "synonymMaps": "", 
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "key": false,
            "searchable": true,
            "retrievable": true,
            "filterable": false,  
            "sortable": false,  
            "facetable": false,
            "analyzer": "",
            "searchAnalyzer": "",
            "indexAnalyzer": "",
            "normalizer": "",
            "synonymMaps": "", 
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        }
    ],
    "vectorSearch": {
        "algorithmConfigurations": [
            {
                "name": "my-vector-config",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ]
    }
}

例: ベクター フィールドと非ベクター フィールドを含むフィールド コレクション

ベクター検索はフィールド レベルで実装されます。 ハイブリッド クエリ シナリオをサポートするには、ベクター クエリと非ベクトル クエリのフィールドのペアを作成します。 "title"、"titleVector"、"content"、"contentVector" フィールドは、この規則に従います。 セマンティック検索も使用する場合は、それらの動作に非ベクトル テキスト フィールドが必要です。

{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "filterable": true
        },
        {
            "name": "title",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "content",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "category",
            "type": "Edm.String",
            "filterable": true,
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        }
    ],
    "corsOptions": {
        "allowedOrigins": [
            "*"
        ],
        "maxAgeInSeconds": 60
    },
    "vectorSearch": {
        "algorithmConfigurations": [
            {
                "name": "my-vector-config",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ]
    },
    "semantic": {
        "configurations": [
            {
                "name": "my-semantic-config",
                "prioritizedFields": {
                    "titleField": {
                        "fieldName": "title"
                    },
                    "prioritizedContentFields": [
                        {
                            "fieldName": "content"
                        }
                    ],
                    "prioritizedKeywordsFields": [
                        {
                            "fieldName": "category"
                        }
                    ]
                }
            }
        ]
    }
}

例: 単純フィールドと複合フィールドが されたインデックス スキーマ

最初の例は、単純フィールドと複合フィールドを含む完全なインデックス スキーマを示しています。 少なくとも 1 つの文字列フィールドに "key" が true に設定されている必要があります。

{
  "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", "normalizer": "tagsNormalizer" },
    { "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, "normalizer": "lowercase" },
          { "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", "normalizer": "tagsNormalizer" }
        ]
    }
  ],
  "suggesters": [ ],
  "analyzers": [ ],
  "normalizers": [ ],
  "encryptionKey": [ ]
}  

例: Suggesters

suggester 定義では、"検索可能" および "取得可能" の文字列フィールドを指定する必要があります (REST API では、すべての単純なフィールドが既定で "retrievable": true されます)。 suggester を定義した後は、クエリ用語の一致または残りの部分を返すかに応じて、Suggestions API またはオートコンプリート APIを使用するクエリ要求で名前で参照できます。

{
  "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", "normalizer": "tagsNormalizer" },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },

  ],
  "suggesters": [
    {  
      "name": "sg",  
      "searchMode": "analyzingInfixMatching",  
      "sourceFields": ["HotelName", "Category", "Tags"]  
    } 
  ]
} 

例: アナライザーとノーマライザー

アナライザーの と ノーマライザー はフィールド定義で参照され、定義済みでもカスタムでもかまいません。 カスタム アナライザーまたはノーマライザーを使用している場合は、"アナライザー" セクションと "ノーマライザー" セクションのインデックスでそれらを指定します。

次の例は、"Tags" のカスタム アナライザーとノーマライザーを示しています。 また、"HotelName" と "Description" の定義済みのノーマライザー (標準) とアナライザー (en.microsoft) についても説明します。

{
  "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, "normalizer": standard  },
    { "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", "normalizer": "tagsNormalizer" },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },

  ],
  "analyzers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
      "name": "tagsAnalyzer",
      "charFilters": [ "html_strip" ],
      "tokenizer": "standard_v2"
    }
  ],
  "normalizers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomNormalizer",
      "name": "tagsNormalizer",
      "tokenFilters": [ "asciifolding", "lowercase" ]
    }
  ]
}  

例: 検索の関連性 の類似性

このプロパティは、フルテキスト検索クエリの検索結果に関連性スコアを作成するために使用されるランク付けアルゴリズムを設定します。 2020 年 7 月 15 日 後に 作成されたサービスでは、類似性アルゴリズムは常に BM25 であるため、このプロパティは無視されます。 2020 年 7 月 15 日 前に 作成された既存のサービスについては、次のようにこのコンストラクトを設定することで BM25 にオプトインできます。

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

例: CORS オプション

ブラウザーではすべてのクロスオリジン要求が禁止されるため、クライアント側の JavaScript では既定では API を呼び出すことはできません。 インデックスに対するクロスオリジン クエリを許可するには、corsOptions 属性を設定して CORS (クロスオリジン リソース共有 (Wikipedia)) を有効にします。 セキュリティ上の理由から、CORS をサポートするのはクエリ API のみです。

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

例: アクセス資格情報を使用した暗号化キー

暗号化キーは、追加の暗号化に使用されるカスタマー マネージド キーです。 詳細については、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)"
        }
    }
} 

例: マネージド ID を使用した暗号化キー

システム割り当てマネージド ID またはユーザー割り当て (プレビュー) マネージド ID を使用して、Azure Key Vault に対する認証を行うことができます。 この場合は、アクセス資格情報を省略するか、null に設定します。 次の例は、ユーザー割り当てマネージド ID を示しています。 システム割り当てマネージド ID を使用するには、アクセス資格情報と ID を省略します。 検索サービスのシステム ID に 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": null,
          "identity" : { 
              "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
              "userAssignedIdentity" : "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"
          }
    }
} 

例: スコアリング プロファイルの

スコアリング プロファイルは、検索結果の上位に表示されるドキュメントに影響を与えるカスタム スコアリング動作を定義するスキーマのセクションです。 スコアリング プロファイルは、フィールドの重みと関数で構成されます。 これを使用するには、クエリ文字列に名前でプロファイルを指定します。 詳細については、「スコアリング プロファイルを検索インデックスに追加する (Azure AI Search REST API)」を参照してください。

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

例: セマンティック構成

セマンティック構成は、ランキング、キャプション、強調表示、回答のセマンティック検索で使用されるフィールドを構成するために使用されるインデックス定義の一部です。 セマンティック検索を使用するには、クエリ時にセマンティック構成の名前を指定する必要があります。 詳細については、「セマンティック クエリを作成する」を参照してください。

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "semantic": {
     "configurations": [
       {
         "name": "my-semantic-config",
         "prioritizedFields": {
           "titleField": {
                 "fieldName": "hotelName"
               },
           "prioritizedContentFields": [
             {
               "fieldName": "description"
             },
             {
               "fieldName": "description_fr"
             }
           ],
           "prioritizedKeywordsFields": [
             {
               "fieldName": "tags"
             },
             {
               "fieldName": "category"
             }
           ]
         }
       }
     ]
   }
}

定義

corsOptions

ブラウザーではすべてのクロスオリジン要求が禁止されるため、クライアント側の JavaScript では既定では API を呼び出すことはできません。 インデックスへのクロスオリジン クエリを許可するには、"corsOptions" 属性を設定して CORS (クロスオリジン リソース共有) を有効にします。 セキュリティ上の理由から、CORS をサポートするのはクエリ API のみです。

defaultScoringProfile

随意。 インデックスで定義されているカスタム スコアリング プロファイルの名前を表す文字列。 カスタム プロファイルがクエリ文字列で明示的に指定されていない場合は常に、既定のプロファイルが呼び出されます。 詳細については、「スコアリング プロファイルを検索インデックスに追加する」を参照してください。

encryptionKey

カスタマー マネージド暗号化キー (CMK)の補足 Azure Key Vault への接続を構成します。 2019 年 1 月 1 日以降に作成された課金対象の検索サービスで利用できます。

キー コンテナーへの接続を認証する必要があります。 この目的には、"accessCredentials" またはマネージド ID を使用できます。

マネージド ID は、システムまたはユーザー割り当て (プレビュー) にすることができます。 検索サービスにシステム割り当てマネージド ID と、キー コンテナーへの読み取りアクセスを許可するロールの割り当ての両方がある場合は、"identity" と "accessCredentials" の両方を省略でき、要求はマネージド ID を使用して認証されます。 検索サービスにユーザー割り当て ID とロールの割り当てがある場合は、"identity" プロパティをその ID のリソース ID に設定します。

田畑

フィールド定義の属性に関する情報が含まれています。

ノーマライザー

ユーザー定義の文字フィルターとトークン フィルターの組み合わせを持つ、カスタム ノーマライザー を定義します。 インデックスでカスタム ノーマライザーを定義した後、フィールド定義に名前で指定できます。

scoringProfiles

スコアリング プロファイルは、フルテキスト検索に適用されます。 プロファイルはインデックスで定義され、プロファイルで定義されている条件を満たす一致するドキュメントに高い検索スコアを与えることができるカスタム ロジックを指定します。 複数のスコアリング プロファイルを作成し、クエリに割り当てることができます。

カスタム プロファイルを作成する場合は、defaultScoringProfile設定して既定にすることができます。 詳細については、「スコアリング プロファイルを検索インデックスに追加する」を参照してください。

セマンティック

セマンティック構成は、ランキング、キャプション、強調表示、回答のセマンティック検索で使用されるフィールドを構成するために使用されるインデックス定義の一部です。 セマンティック構成は、タイトル フィールド、優先順位付けされたコンテンツ フィールド、および優先順位付けされたキーワード フィールドで構成されます。 3 つのサブプロパティ (titleField、prioritizedKeywordsFields、prioritizedContentFields) ごとに少なくとも 1 つのフィールドを指定する必要があります。 Edm.String 型または Collection(Edm.String) 型のフィールドは、セマンティック構成の一部として使用できます。

セマンティック検索を使用するには、クエリ時にセマンティック構成の名前を指定する必要があります。 詳細については、「セマンティック クエリを作成する」を参照してください。

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "semantic": {
     "configurations": [
       {
         "name": "name of the semantic configuration",
         "prioritizedFields": {
           "titleField": {
                 "fieldName": "..."
               },
           "prioritizedContentFields": [
             {
               "fieldName": "..."
             },
             {
               "fieldName": "..."
             }
           ],
           "prioritizedKeywordsFields": [
             {
               "fieldName": "..."
             },
             {
               "fieldName": "..."
             }
           ]
         }
       }
     ]
   }
}

相似

2020 年 7 月 15 日より前に作成されたサービスに適用される省略可能なプロパティ。 これらのサービスでは、2020 年 7 月に導入された BM25 ランク付けアルゴリズムを使用するようにこのプロパティを設定できます。 有効な値には、"#Microsoft.Azure.Search.ClassicSimilarity" (前の既定値) または "#Microsoft.Azure.Search.BM25Similarity"が含まれます。

2020 年 7 月以降に作成されたすべてのサービスでは、このプロパティを設定しても効果はありません。 新しいサービスはすべて、フルテキスト検索の唯一のランク付けアルゴリズムとして BM25 を使用します。 詳細については、「Azure AI Searchの ランク付けアルゴリズム」を参照してください。

suggesters

オートコンプリートや候補などの部分的なクエリで一致するプレフィックスを格納するコンストラクトを指定します。

vectorSearch

vectorSearch オブジェクトを使用すると、ベクター検索プロパティを構成できます。 現在、アルゴリズム構成のみを構成できます。 これにより、ベクター フィールドに使用されるアルゴリズムの種類とアルゴリズム パラメーターの構成が可能になります。 複数の構成を使用できます。 ベクター フィールドによって参照される構成は、変更も削除もできません。 参照されていない構成は、変更または削除できます。 (フィールド コレクション内の) ベクター フィールド定義では、フィールドが使用するベクター検索アルゴリズムの構成 (vectorSearchConfiguration プロパティを使用) を指定する必要があります。

"vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "my-vector-config",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]
}

hnswParameters

このオブジェクトには、アルゴリズム パラメーターを hnsw するためのカスタマイズが含まれています。 すべてのプロパティは省略可能であり、省略された場合は既定値が使用されます。

efSearch はクエリ時間パラメーターであるため、既存のフィールドがアルゴリズム構成を使用している場合でも、この値を更新できます。

関連項目

• HTTP 状態コード
• スコアリング プロファイルを検索インデックス に追加する
• ドキュメント検索 API の
• サポートされているデータ型の
• 字句アナライザーの
• ポータルで Azure AI Search インデックスを作成
• セマンティック構成 を作成する