다음을 통해 공유

문서 추가, 업데이트 또는 삭제(미리 보기 REST API)

  • 아티클

적용 : 2023-07-01-Preview. 이 버전은 더 이상 지원되지 않습니다. 업그레이드는 즉시 최신 버전으로.

중요하다

2023-07-01-Preview는 다음을 추가합니다.

  • 문서의 벡터 필드를 지원합니다.

HTTP POST를 사용하여 벡터 필드가 포함된 문서를 지정된 인덱스로 푸시할 수 있습니다. 대규모 업데이트의 경우 일괄 처리(일괄 처리당 최대 1000개 문서 또는 일괄 처리당 약 16MB)는 인덱싱 성능을 향상시킵니다.

POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2023-07-01-Preview  
  Content-Type: application/json   
  api-key: [admin key]

URI 매개 변수

매개 변수 묘사
서비스 이름 필수. 이 값을 검색 서비스의 고유한 사용자 정의 이름으로 설정합니다.
인덱스 이름 필수. 이 값을 문서를 받는 인덱스의 이름으로 설정합니다. 문서를 한 번에 하나의 인덱스로만 게시할 수 있습니다.
api-version 더 많은 버전은 API 버전 참조하세요.

요청 헤더

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

필드 묘사
Content-Type 필수. 이 값을 application/json
api-key Azure 역할 사용하고 요청에 전달자 토큰이 제공된 경우 선택 사항입니다. 그렇지 않으면 키가 필요합니다. api-key는 검색 서비스에 대한 요청을 인증하는 고유한 시스템 생성 문자열입니다. 문서를 업로드하려면 관리자 API 키가 필요합니다. 자세한 내용은 키 인증 사용하여 Azure AI Search에 연결을 참조하세요.

요청 본문

요청 본문에는 인덱싱할 문서가 하나 이상 포함되어 있습니다. 문서는 대/소문자를 구분하는 키를 통해 고유하게 식별됩니다. 각 문서는 "upload", "delete", "merge" 또는 "mergeOrUpload" 작업과 연결됩니다. 업로드 요청에는 문서 데이터를 키/값 쌍 집합으로 포함해야 합니다.

벡터 필드는 Collection(Edm.Single)형식입니다. 벡터 데이터는 단정밀도 부동 소수점 숫자의 배열로 구성됩니다.

벡터 필드는 원래 콘텐츠의 복잡성, 길이 또는 형식에 따라 수천 개의 포함을 포함할 수 있습니다. Azure AI Search는 콘텐츠를 포함으로 변환하지 않습니다. 인덱스에 푸시하는 문서에는 이전에 생성한 포함 항목이 포함되어야 합니다.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (key/value pairs matching index schema),
      "vector_field_name": [ array of single-precision floating point numbers ]
        ...  
    },  
    ...  
  ]  
}
재산 묘사
@search.action 필수. 유효한 값은 "upload", "delete", "merge" 또는 "mergeOrUpload"입니다. 기본값은 "upload"입니다.
key_field_name 필수. 문서 키 역할을 하고 고유 값만 포함하는 인덱스의 필드 정의입니다. 문서 키는 문자, 숫자, 대시("-"), 밑줄("_"), 등호("=")만 포함할 수 있으며 대/소문자를 구분합니다.
field_name 필수. 필드 이름이 인덱스 정의의 필드 이름에 해당하는 이름-값 쌍입니다. 값은 사용자 정의이지만 필드 형식에 대해 유효해야 합니다.

응답

상태 코드: 성공적인 응답을 위해 200이 반환됩니다. 즉, 모든 항목이 지속적으로 저장되고 인덱싱이 시작되었습니다. 인덱싱은 백그라운드에서 실행되며 인덱싱 작업이 완료된 후 몇 초 후에 새 문서(즉, 쿼리 가능하고 검색 가능)를 사용할 수 있습니다.

성공적인 인덱싱은 상태 속성이 모든 항목에 대해 true로 설정된 경우 표시됩니다. statusCode 속성은 201(새로 업로드된 문서의 경우) 또는 200(병합되거나 삭제된 문서의 경우)이어야 합니다.

예제

예제: 텍스트 및 벡터 콘텐츠 사용하여 두 개의 문서 업로드

가독성을 위해 다음 예제에서는 문서 및 포함의 하위 집합을 보여 줍니다. 문서 업로드 요청의 본문은 각각 "titleVector" 및 "contentVector"에 대한 전체 포함 집합이 있는 108개의 문서로 구성됩니다.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "value": [
        {
            "id": "1",
            "title": "Azure App Service",
            "content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
            "category": "Web",
            "titleVector": [
                -0.02250031754374504,
                 . . . 
                        ],
            "contentVector": [
                -0.024740582332015038,
                 . . .
            ],
            "@search.action": "upload"
        },
        {
            "id": "2",
            "title": "Azure Functions",
            "content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
            "category": "Compute",
            "titleVector": [
                -0.020159931853413582,
                . . .
            ],
            "contentVector": [
                -0.02780858241021633,,
                 . . .
            ],
            "@search.action": "upload"
        }
        . . .
    ]
}

메모

표준 시간대 정보가 있는 DateTimeOffset 값을 인덱스에 업로드하면 Azure AI Search는 이러한 값을 UTC로 정규화합니다. 예를 들어 2019-01-13T14:03:00-08:00은 2019-01-13T22:03:00Z로 저장됩니다. 표준 시간대 정보를 저장해야 하는 경우 인덱싱에 추가 열을 추가합니다.

참고 항목