데이터 원본 만들기(Azure AI Search REST API)

  • 아티클

Azure AI Search에서 데이터 원본은 인덱서와 함께 사용되며, 대상 인덱스의 요청 시 또는 예약된 데이터 새로 고침에 대한 연결 정보를 제공하고 지원되는 Azure 데이터 원본에서 데이터를 가져옵니다.

요청에 POST 또는 PUT을 사용할 수 있습니다. 둘 중 하나의 경우 요청 본문의 JSON 문서는 개체 정의를 제공합니다.

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

또는 PUT을 사용하고 URI에 이름을 지정할 수 있습니다.

PUT https://[service name].search.windows.net/datasources/[data source name]?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]

모든 서비스 요청에는 HTTPS를 사용해야 합니다. 개체가 없으면 개체가 만들어집니다. 이미 있는 경우 새 정의로 업데이트됩니다.

참고

만들 수 있는 최대 인덱스 수는 가격 책정 계층에 따라 다릅니다. 자세한 내용은 서비스 제한을 참조하세요.

URI 매개 변수

매개 변수 Description
서비스 이름 필수 사항입니다. 검색 서비스의 고유한 사용자 정의 이름으로 설정합니다.
데이터 원본 이름(data source name) PUT을 사용하는 경우 URI에 필요합니다. 이름은 소문자여야 하고, 문자나 숫자로 시작하고, 슬래시나 점이 없고, 128자 미만이어야 합니다. 이름은 문자 또는 숫자로 시작해야 하지만 대시가 연속되지 않는 한 나머지 이름에는 문자, 숫자 및 대시가 포함될 수 있습니다.
api-version 필수 사항입니다. 지원되는 버전 목록은 API 버전을 참조하세요.

요청 헤더

다음 표에서는 필수 요청 헤더와 선택적 요청 헤더에 대해 설명합니다.

필드 Description
콘텐츠 형식 필수 사항입니다. application/json
api-key Azure 역할을 사용하고 요청에 전달자 토큰이 제공된 경우 선택 사항이며, 그렇지 않으면 키가 필요합니다. 요청 만들기에는 쿼리 키와 api-key 달리 관리자 키로 설정된 헤더가 포함되어야 합니다. 자세한 내용은 키 인증을 사용하여 Azure AI Search에 연결을 참조하세요.

요청 본문

요청 본문에는 데이터 원본 정의가 포함됩니다. 데이터 원본 정의에는 데이터 원본의 형식, 데이터를 읽는 데 필요한 자격 증명 그리고 선택적 데이터 변경/삭제 검색 정책이 들어 있으며, 이러한 정책은 정기적으로 예약되는 인덱서와 함께 사용할 때 데이터 원본에서 변경되거나 삭제된 데이터를 효율적으로 식별하는 데 사용됩니다.

다음 JSON은 정의의 기본 부분에 대한 개략적인 표현입니다.

{   
    "name" : (optional on PUT; required on POST) "Name of the data source",  
    "description" : (optional) "Anything you want, or nothing at all",  
    "type" : (required) "Must be a supported data source",
    "credentials" : (required) { "connectionString" : "Connection string for your data source" },
    "container": {
        "name": "Name of the table, view, collection, or blob container you wish to index",
        "query": (optional) 
    },
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "encryptionKey":(optional) { }
}

요청에는 다음 속성이 포함됩니다.

속성 Description
name 필수 사항입니다. 데이터 원본의 이름입니다. 데이터 원본 이름은 소문자, 숫자 또는 대시만 포함해야 하며 대시로 시작하거나 끝낼 수 없으며 128자로 제한됩니다.
description 선택적 설명입니다.
type 필수 사항입니다. 지원되는 데이터 원본 유형
azuresql
중 하나여야 합니다. Azure SQL Database, Azure SQL Managed Instance 또는 Azure VM
cosmosdb에서 실행되는 SQL Server instance NoSQL용 Azure Cosmos DB, MongoDB용 Azure Cosmos DB(미리 보기) 또는 Azure TableStorage
azurefile for Azure Files(미리 보기)azureblob
용 Azure Data Lake Storage Gen2

azuretableadlsgen2 Azure Blob Storage 대한 Azure Cosmos DB for Apache Gremlin(미리 보기)
mysqlAzure Database for MySQL(미리 보기)
sharepointMicrosoft 365의 SharePoint용(미리 보기)
자격 증명 필수 사항입니다. 데이터 원본에 connectionString 대한 연결 문자열 지정하는 속성이 포함되어 있습니다. 연결 문자열 형식은 데이터 원본 형식에 따라 달라집니다.

Azure SQL Database의 경우 일반적인 SQL Server 연결 문자열. Azure Portal 사용하여 연결 문자열 검색하는 경우 옵션을 선택합니다ADO.NET connection string.

Azure Cosmos DB의 경우 연결 문자열 형식"AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]"이어야 합니다. 모든 값이 필요합니다. Azure Portal에서 이러한 값을 확인할 수 있습니다.

Azure Blob Storage 경우 연결 문자열 형식은 Azure AI Search에서 Blob 인덱싱을 구성하는 방법의 자격 증명 섹션에 정의되어 있습니다.

Azure Storage, Azure SQL Database 및 Azure Cosmos DB는 연결 문자열 계정 키를 포함하지 않는 관리 ID 연결 문자열 지원합니다. 관리 ID 연결 문자열 형식을 사용하려면 관리 ID를 사용하여 데이터 원본에 대한 인덱서 연결 설정 지침을 따릅니다.

데이터 원본을 업데이트하는 경우 연결 문자열 필요하지 않습니다. 또는 <redacted> 값 <unchanged> 은 실제 연결 문자열 대신 사용할 수 있습니다.
container 필수 사항입니다. (필수) 및 query (선택 사항) 속성을name

사용하여 name 인덱싱할 데이터를 지정합니다. :
Azure SQL 테이블 또는 뷰를 지정합니다. [dbo].[mytable]과 같은 스키마로 한정된 이름을 사용할 수 있습니다.
Azure Cosmos DB의 경우 SQL API 컬렉션을 지정합니다.
Azure Blob Storage 스토리지 컨테이너를 지정합니다.
Azure Table Storage의 경우 테이블의 이름을 지정합니다.

query:
Azure Cosmos DB의 경우 임의 JSON 문서 레이아웃을 Azure AI Search가 인덱싱할 수 있는 플랫 스키마로 평면화하는 쿼리를 지정할 수 있습니다.
Azure Blob Storage 경우 Blob 컨테이너 내에서 가상 폴더를 지정할 수 있습니다. 예를 들어 BLOB 경로 mycontainer/documents/blob.pdf, documents의 경우 가상 폴더로 사용할 수 있습니다.
Azure Table Storage의 경우 가져올 행 집합을 필터링하는 쿼리를 지정할 수 있습니다.
Azure SQL 쿼리는 지원되지 않습니다. 대신 보기를 사용합니다.
dataChangeDetectionPolicy 선택 사항입니다. 변경된 데이터 항목을 식별하는 데 사용됩니다. 지원되는 정책은 데이터 원본 형식에 따라 다릅니다. 유효한 정책은 높은 워터마크 변경 검색 정책 및 SQL 통합 변경 검색 정책입니다.

상위 워터마크 변경 검색 정책은 다른 업데이트와 함께 업데이트되는 기존 열 또는 속성에 따라 달라지고(모든 삽입은 워터마크 열에 대한 업데이트를 초래함) 값의 변경이 더 높습니다. Cosmos DB 데이터 원본의 경우 속성을 사용해야 _ts 합니다. Azure SQL 인덱싱된 rowversion 열은 높은 워터 마크 정책과 함께 사용하기에 이상적인 후보입니다. Azure Storage의 경우 변경 검색은 lastModified 값을 사용하여 기본 제공되므로 Blob 또는 테이블 스토리지에 대한 dataChangeDetectionPolicy를 설정할 필요가 없습니다.

SQL 통합 변경 검색 정책은 SQL Server 네이티브 변경 검색 기능을 참조하는 데 사용됩니다. 이 정책은 테이블과 함께만 사용할 수 있습니다. 보기와 함께 사용할 수 없습니다. 이 정책을 사용하려면 사용 중인 테이블에 대해 변경 내용 추적을 사용하도록 설정해야 합니다. 지침은 변경 내용 추적 설정 및 해제 를 참조하세요. 인덱서의 변경 검색 지원에 대한 자세한 내용은 Azure SQL 콘텐츠에 연결 및 인덱싱을 참조하세요.
dataDeletionDetectionPolicy 선택 사항입니다. 삭제된 데이터 항목을 식별하는 데 사용됩니다. 현재 지원되는 유일한 정책은 데이터 원본의 '일시 삭제' 열 또는 속성 값에 따라 삭제된 항목을 식별하는 일시 삭제 정책입니다.

문자열, 정수 또는 부울 값이 있는 열만 지원됩니다. softDeleteMarkerValue 로 사용되는 값은 해당 열에 정수 또는 부울 값이 있는 경우에도 문자열이어야 합니다. 예를 들어 데이터 원본에 표시되는 값이 1인 경우 "1"을 softDeleteMarkerValue로 사용합니다.
encryptionKey 선택 사항입니다. Azure Key Vault 관리되는 사용자 고유의 키로 미사용 데이터 원본을 암호화하는 데 사용됩니다. 2019-01-01 또는 그 이후에 생성된 청구 가능한 검색 서비스에 사용할 수 있습니다.

encryptionKey 섹션에는 사용자 정의 keyVaultKeyName (필수), 시스템 생성 keyVaultKeyVersion (필수) 및 keyVaultUri 제공 키(필수, DNS 이름이라고도 함)가 포함되어 있습니다. 예제 URI는 "https://my-keyvault-name.vault.azure.net"일 수 있습니다.

필요에 따라 관리되는 시스템 ID를 사용하지 않는지 지정할 accessCredentials 수 있습니다. 의 accessCredentials 속성에는 지정된 Azure Key Vault 대한 액세스 권한이 부여된(Microsoft Entra ID 애플리케이션 ID) 및 applicationSecret (등록된 애플리케이션의 인증 키)가 포함 applicationId 됩니다. 다음 섹션의 예제에서는 구문을 보여 줍니다.

응답

요청이 성공적으로 실행되면 '201 생성됨'이 반환됩니다.

예제

예: 변경 검색을 사용하여 Azure SQL(상위 워터마크 변경 검색 정책)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName" : "RowVersion" }
}

예: 변경 검색을 사용하여 Azure SQL(SQL 통합 변경 내용 추적 정책)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy" }
}

예: 삭제 검색을 사용하여 변경 검색을 사용하여 Azure SQL

삭제 검색에 대한 속성은 및 softDeleteMarkerValue입니다softDeleteColumnName.

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },   
    "dataDeletionDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy", "softDeleteColumnName" : "IsDeleted", "softDeleteMarkerValue" : "true" }  
}

예: 필수 속성만 있는 데이터 원본

데이터 원본을 일회성 데이터 복사본에만 사용하려는 경우 변경 및 삭제 검색과 관련된 선택적 속성을 생략할 수 있습니다.

{   
    "name" : "asqldatasource",  
    "description" : "anything you want, or nothing at all",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" }  
}

예: 자격 증명 생략

데이터 원본을 업데이트하려는 경우 자격 증명이 필요하지 않습니다. 또는 <redacted> 값 <unchanged> 은 연결 문자열 대신 사용할 수 있습니다.

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
}

예: 암호화 키

암호화 키는 추가 암호화에 사용되는 고객 관리형 키입니다. 자세한 내용은 Azure Key Vault 고객 관리형 키를 사용한 암호화를 참조하세요.

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
    "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": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}

참고 항목