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

Azure Cognitive 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를 사용해야 합니다. 존재 하지 않는 개체는 생성 됩니다. 이미 있으면 새 정의로 업데이트됩니다.

참고

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

URI 매개 변수

매개 변수 설명
서비스 이름 필수 요소. 이를 검색 서비스의 고유한 사용자 정의 이름으로 설정 합니다.
데이터 원본 이름(data source name) PUT을 사용 하는 경우 URI에 필요 합니다. 이름은 소문자 여야 하 고, 문자나 숫자로 시작 하 고, 슬래시 또는 마침표를 사용 하지 않아야 하며, 128 자 미만 이어야 합니다. 이름을 문자나 숫자로 시작한 후에는 대시를 연속으로 사용 하지 않는 한, 이름의 나머지 부분에 문자, 숫자 및 대시를 포함할 수 있습니다.
api-version 필수 요소. 현재 버전은 api-version=2020-06-30입니다. 사용 가능한 버전 목록은 Azure Cognitive Search의 API 버전 을 참조 하세요.

요청 헤더

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

필드 Description
콘텐츠 형식 필수 요소. application/json
api-key 필수 요소. api-key는 Search 서비스에 대한 요청을 인증하는 데 사용되며, 서비스에 고유한 문자열 값입니다. 만들기 요청은 api-key 쿼리 키가 아니라 관리 키로 설정 된 헤더를 포함 해야 합니다.

api-keyAzure Portal의 서비스 대시보드에서를 가져올 수 있습니다. 자세한 내용은 기존 키 찾기를 참조 하세요.

요청 본문

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

다음 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" : (required) { "name" : "Name of the table, collection, or blob container you wish to index" },  
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "encryptionKey":(optional) { }
}  

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

속성 설명
name 필수 요소. 데이터 원본의 이름입니다. 데이터 원본 이름은 소문자, 숫자 또는 대시만 포함할 수 있고 대시로 시작하거나 끝날 수 없으며 128자로 제한됩니다.
description 선택적 설명입니다.
형식 필수 요소. 다음과 같은 지원되는 데이터 원본 유형 중 하나여야 합니다.

azuresqlAzure SQL Database
cosmosdbAZURE COSMOS DB SQL API 의 경우
azureblobAzure Blob Storage
adlsgen2Azure Data Lake Storage Gen2
azuretableAzure Table Storage
자격 증명 필수 요소. connectionString데이터 원본에 대 한 연결 문자열을 지정 하는 속성을 포함 합니다. 연결 문자열의 형식은 데이터 원본 유형에 따라 달라 집니다.

Azure SQL 데이터베이스의 경우에는 일반적인 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의 경우 연결 문자열 형식은 Cognitive Search에서 Blob 인덱싱을 구성 하는 방법의 자격 증명 섹션에서 정의 됩니다.

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

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

name:
Azure SQL의 경우 테이블 또는 뷰를 지정 합니다. [dbo].[mytable]과 같은 스키마로 한정된 이름을 사용할 수 있습니다.
Azure Cosmos DB의 경우 SQL API 컬렉션을 지정 합니다.
Azure Blob Storage에 대해 저장소 컨테이너를 지정 합니다.
Azure Table Storage의 경우 테이블의 이름을 지정 합니다.

query:
Azure Cosmos DB의 경우 Azure Cognitive Search 인덱싱할 수 있는 플랫 스키마로 임의 JSON 문서 레이아웃을 평면화 하는 쿼리를 지정할 수 있습니다.
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 또는 Table Storage에 대해 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 있습니다.

필요에 따라 관리 accessCredentials 시스템 ID를 사용하지 않는지 지정할 수 있습니다. 의 accessCredentials 속성에는 applicationId 지정된 Azure Key Vault 대한 액세스 권한이 부여된 (Azure Active Directory 애플리케이션 ID) 및 applicationSecret (지정된 Azure AD 애플리케이션의 인증 키)가 포함됩니다. 다음 섹션의 예제에서는 구문을 보여 줍니다.
disabled 선택 사항입니다. 인덱서가 비활성화되었는지 여부를 나타내는 부울 값입니다. False(기본값).

응답

요청이 성공적으로 실행되면 '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 변경 검색

삭제 검색 속성은 softDeleteColumnNamesoftDeleteMarkerValue 입니다.

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

예제: 자격 증명 생략

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

{
    "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": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

참고 항목