Azure Data Factory または Synapse Analytics を使用して Azure AI Search インデックスにデータをコピーする

[アーティクル]
01/05/2024

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

企業向けのオールインワン分析ソリューション、Microsoft Fabric の Data Factory をお試しください。 Microsoft Fabric は、データ移動からデータサイエンス、リアルタイム分析、ビジネスインテリジェンス、レポートまで、あらゆるものをカバーしています。無料で新しい試用版を開始する方法について説明します。

この記事では、Azure Data Factory または Synapse Analytics パイプラインで Copy アクティビティを使用して、Azure AI インデックスにデータをコピーする方法について説明します。この記事は、コピーアクティビティの概要を示しているコピーアクティビティの概要に関する記事に基づいています。

サポートされる機能

この Azure AI Search コネクタは、次の機能でサポートされています。

サポートされる機能	IR	マネージドプライベートエンドポイント
Copy アクティビティ (-/シンク)	1.1	✓

① Azure 統合ランタイム ② セルフホステッド統合ランタイム

サポートされているソースデータストアから検索インデックスにデータをコピーできます。コピーアクティビティによってソースまたはシンクとしてサポートされているデータストアの一覧については、サポートされているデータストアに関する記事の表をご覧ください。

作業の開始

パイプラインでコピーアクティビティを実行するには、次のいずれかのツールまたは SDK を使用します。

UI を使用して Azure Search のリンクサービスを作成する

次の手順を使用して、Azure portal UI で Azure Search のリンクサービスを作成します。

Azure Data Factory または Synapse ワークスペースの [管理] タブに移動し、[リンクされたサービス] を選択して、[新規] をクリックします。
- Azure Data Factory
- Azure Synapse
Search を検索し、Azure Search コネクタを選択します。
サービスの詳細を構成し、接続をテストして、新しいリンクサービスを作成します。

コネクタの構成の詳細

次のセクションでは、Azure AI Search コネクタに固有の Data Factory エンティティの定義に使用されるプロパティについて詳しく説明します。

リンクされたサービスのプロパティ

Azure AI Search のリンクサービスでは、次のプロパティがサポートされます。

プロパティ	Description	必須
type	type プロパティを AzureSearch に設定する必要があります。	はい
url	検索サービスの URL。	はい
key	検索サービスの管理者キー。このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。	はい
connectVia	データストアに接続するために使用される統合ランタイム。 Azure 統合ランタイムまたは自己ホスト型統合ランタイム (データストアがプライベートネットワークにある場合) を使用できます。指定されていない場合は、既定の Azure 統合ランタイムが使用されます。	いいえ

重要

Azure AI Search のリンクサービスでクラウドデータストアのデータを検索インデックスにコピーする場合は、connactVia で明示的なリージョンを指定して Azure Integration Runtime を参照する必要があります。そのリージョンを Search サービスが存在するリージョンとして設定します。 Azure 統合ランタイムから説明します。

例:

{
    "name": "AzureSearchLinkedService",
    "properties": {
        "type": "AzureSearch",
        "typeProperties": {
            "url": "https://<service>.search.windows.net",
            "key": {
                "type": "SecureString",
                "value": "<AdminKey>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

データセットのプロパティ

データセットを定義するために使用できるセクションとプロパティの完全な一覧については、データセットに関する記事をご覧ください。このセクションでは、Azure AI Search データセットでサポートされるプロパティの一覧を示します。

データを Azure AI Search にコピーするには、次のプロパティがサポートされています。

プロパティ	Description	必須
type	データセットの type プロパティは、AzureSearchIndex を設定する必要があります。	はい
indexName	検索インデックスの名前。サービスでは、インデックスは作成されません。 Azure AI Search にこのインデックスが存在する必要があります。	はい

例:

{
    "name": "AzureSearchIndexDataset",
    "properties": {
        "type": "AzureSearchIndex",
        "typeProperties" : {
            "indexName": "products"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Azure AI Search linked service name>",
            "type": "LinkedServiceReference"
        }
   }
}

コピーアクティビティのプロパティ

アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインに関する記事を参照してください。このセクションでは、Azure AI Search ソースでサポートされるプロパティの一覧を示します。

シンクとしての Azure AI Search

Azure AI Search にデータをコピーするには、Copy アクティビティのソースの種類を AzureSearchIndexSink に設定します。コピーアクティビティの sink セクションでは、次のプロパティがサポートされます。

プロパティ	Description	必須
type	コピーアクティビティのソースの type プロパティは AzureSearchIndexSink を設定する必要があります。	はい
writeBehavior	ドキュメントがそのインデックスに既に存在する場合に、マージするか置換するかを指定します。詳細については、「WriteBehavior プロパティ」を参照してください。使用可能な値: マージ (既定値) およびアップロード。	いいえ
writeBatchSize	バッファーサイズが writeBatchSize に達すると、検索インデックスにデータをアップロードします。詳細については、「WriteBatchSize プロパティ」を参照してください。使用可能な値: 1 ～ 1,000 の整数。既定値は 1000 です。	いいえ
maxConcurrentConnections	アクティビティの実行中にデータストアに対して確立されたコンカレント接続数の上限。コンカレント接続を制限する場合にのみ、値を指定します。	いいえ

WriteBehavior プロパティ

データを書き込むときに AzureSearchSink で upsert されます。つまり、ドキュメントを書き込むときに検索インデックスにそのドキュメントのキーが既に存在する場合は、Azure AI Search は競合の例外をスローするのではなく、既存のドキュメントを更新します。

AzureSearchSink で提供される upsert 動作 (AzureSearch SDK の使用による) は、次の 2 とおりあります。

マージ: 新しいドキュメントのすべての列を既存の列と結合します。新しいドキュメント内に null 値を持つ列がある場合は、既存の列の値が保持されます。
アップロード: 既存のドキュメントが新しいドキュメントで置き換えられます。新しいドキュメントで指定されていない列の場合は、既存のドキュメントに null 以外の値があるかどうかに関係なく、値は null に設定されます。

既定の動作はマージです。

WriteBatchSize プロパティ

Azure AI Search サービスでは、バッチとしてのドキュメントの書き込みをサポートしています。バッチには、1 ～ 1,000 のアクションを含めることができます。 1 つのアクションで、1 つのドキュメントのアップロード/マージ操作の実行を処理します。

例:

"activities":[
    {
        "name": "CopyToAzureSearch",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Azure AI Search output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "AzureSearchIndexSink",
                "writeBehavior": "Merge"
            }
        }
    }
]

データ型のサポート

次の表に、Azure AI Search データ型がサポートされているかどうかを示します。

Azure AI Search のデータ型	Azure AI Search のシンクでサポートされている
String	Y
Int32	Y
Int64	Y
Double	Y
Boolean	Y
DataTimeOffset	Y
String Array	N
GeographyPoint	N

現在、ComplexType などの他のデータ型はサポートされていません。 Azure AI Search でサポートされているデータ型の完全な一覧については、「サポートされているデータ型 (Azure AI Search)」を参照してください。

Copy アクティビティでソースおよびシンクとしてサポートされるデータストアの一覧については、サポートされるデータストアに関するセクションを参照してください。