빠른 시작: REST를 사용한 키워드 검색
Azure AI 검색의 REST API는 미리 보기 기능을 포함하여 모든 기능에 프로그래밍 방식으로 액세스할 수 있도록 하며 기능이 작동하는 방식을 쉽게 알아볼 수 있습니다. 이 빠른 시작에서 검색 REST API를 호출하여 Azure AI 검색에서 인덱스를 만들고 로드하고 쿼리하는 방법을 알아봅니다.
Azure 구독이 아직 없는 경우 시작하기 전에 체험 계정을 만듭니다.
필수 조건
Azure AI 검색. 현재 구독에서 기존 Azure AI 검색 리소스를 만들거나 찾습니다. 이 빠른 시작에서는 체험 서비스를 사용할 수 있습니다.
파일 다운로드
GitHub에서 REST 샘플을 다운로드하여 이 빠른 시작에서 요청을 보냅니다. 지침은 GitHub에서 파일 다운로드에서 확인할 수 있습니다.
이 문서의 지침을 사용하여 로컬 시스템에서 새 파일을 시작하고 수동으로 요청을 만들 수도 있습니다.
검색 서비스 엔드포인트 가져오기
Azure Portal에서 검색 서비스 엔드포인트를 찾을 수 있습니다.
Azure Portal에 로그인하고 검색 서비스를 찾습니다.
개요 홈페이지에서 URL을 찾습니다. 엔드포인트의 예는 다음과 같습니다.
https://mydemo.search.windows.net
이후 단계에서 이 엔드포인트를 .rest 또는 .http 파일에 붙여넣습니다.
액세스 구성
검색 엔드포인트에 대한 요청은 인증 및 권한 부여를 받아야 합니다. 이 작업에 API 키 또는 역할을 사용할 수 있습니다. 키는 시작하기가 더 쉽지만 역할이 더 안전합니다.
역할 기반 연결의 경우 다음 지침에 따라 클라이언트 앱의 ID가 아닌 사용자 ID로 Azure AI 검색에 연결합니다.
옵션 1: 키 사용
설정>키를 선택한 다음, 관리자 키를 복사합니다. 관리자 키는 개체를 추가, 수정, 삭제하는 데 사용됩니다. 교환 가능한 관리자 키는 2개입니다. 둘 중 하나를 복사합니다. 자세한 내용은 키 인증을 사용하여 Azure AI 검색에 연결을 참조하세요.
이후 단계에서 이 키를 .rest 또는 .http 파일에 붙여넣습니다.
옵션 2: 역할 사용
검색 서비스가 역할 기반 액세스에 대해 구성되어 있는지 확인합니다. 개발자 액세스를 위한 역할 할당이 미리 구성되어 있어야 합니다. 역할 할당은 검색 인덱스를 생성, 로드 및 쿼리할 수 있는 권한을 부여해야 합니다.
이 섹션에서는 Azure CLI, Azure PowerShell 또는 Azure Portal을 사용하여 개인 ID 토큰을 가져옵니다.
Azure CLI에 로그인합니다.
az login개인 ID 토큰을 가져옵니다.
az account get-access-token --scope https://search.azure.com/.default
이후 단계에서 개인 ID 토큰을 .rest 또는 .http 파일에 붙여넣습니다.
참고 항목
이 섹션에서는 사용자를 대신하여 Azure AI 검색에 연결하는 로컬 클라이언트를 사용한다고 가정합니다. 애플리케이션이 Microsoft Entra ID에 등록되어 있다고 가정하고 클라이언트 앱에 대한 토큰을 가져오는 방식을 사용할 수도 있습니다.
Visual Studio Code 설정
Visual Studio Code용 REST 클라이언트에 익숙하지 않은 경우 이 섹션에는 이 빠른 시작의 작업을 완료할 수 있도록 설정이 포함되어 있습니다.
Visual Studio Code를 시작하고 확장 타일을 선택합니다.
REST 클라이언트를 검색하고 설치를 선택합니다.
.rest또는.http파일 확장자를 사용하여 명명된 새 파일을 열거나 만듭니다.API 키를 사용하는 경우 다음 예를 붙여넣습니다.
@baseUrl및@apiKey자리 표시자를 이전에 복사한 값으로 바꿉니다.@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE @apiKey = PUT-YOUR-SEARCH-SERVICE-API-KEY-HERE ### List existing indexes by name GET {{baseUrl}}/indexes?api-version=2024-07-01&$select=name HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}또는 역할을 사용하는 경우 이 예를 붙여넣습니다.
@baseUrl및@token자리 표시자를 이전에 복사한 값으로 바꿉니다.@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE ### List existing indexes by name GET {{baseUrl}}/indexes?api-version=2024-07-01&$select=name HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}}요청 보내기를 선택합니다. 인접한 창에 응답이 표시됩니다. 기존 인덱스가 있는 경우 인덱스가 나열됩니다. 그러지 않으면 목록은 비어 있습니다. HTTP 코드가
200 OK인 경우 다음 단계를 수행할 준비가 된 것입니다.
주요 정보:
- 매개 변수는
@접두사를 사용하여 지정됩니다. ###은 REST 호출을 지정합니다. 다음 줄에는HTTP/1.1을 포함해야 하는 요청이 포함됩니다.Send request가 요청 위에 표시되어야 합니다.
- 매개 변수는
인덱스 만들기
.rest 파일에 두 번째 요청을 추가합니다. 인덱스 만들기(REST)는 검색 인덱스를 만들고 검색 서비스에 물리적 데이터 구조를 설정합니다.
다음 예제를 붙여넣어 검색 서비스에
hotels-quickstart인덱스를 만듭니다.### Create a new index POST {{baseUrl}}/indexes?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "name": "hotels-quickstart", "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.lucene"}, {"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}, {"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}, {"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} ] } ] }요청 보내기를 선택합니다.
HTTP/1.1 201 Created응답이 있어야 하며 응답 본문에는 인덱스 스키마의 JSON 표현이 포함되어야 합니다.Header name must be a valid HTTP token ["{"]오류가 발생하면api-key와 요청 본문 사이에 빈 줄이 있는지 확인합니다. HTTP 504가 표시될 경우 URL이 HTTPS를 지정하는지 확인합니다. HTTP 400 또는 404가 표시되는 경우 요청 본문에서 복사/붙여 넣기 오류가 없는지 확인합니다. HTTP 403은 일반적으로 API 키에 문제가 있음을 나타냅니다. 키가 잘못되었거나 API 키를 지정하는 방법에 문제가 있는 경우입니다.이제 파일에 요청이 여러 개 있습니다.
###이 새 요청을 시작하고 각 요청은 독립적으로 실행됩니다.
인덱스 정의 정보
인덱스 스키마 내에서 필드 컬렉션은 문서 구조를 정의합니다. 업로드하는 각 문서에는 이러한 필드가 있어야 합니다. 각 필드는 EDM(엔터티 데이터 모델) 데이터 형식에 할당되어야 합니다. 문자열 필드는 전체 텍스트 검색에 사용됩니다. 숫자 데이터를 검색 가능하게 하려면 데이터 형식이 Edm.String인지 확인합니다. Edm.Int32와 같은 다른 데이터 형식은 필터링, 정렬, 패싯 및 검색이 가능하지만 전체 텍스트 검색은 가능하지 않습니다.
필드의 특성에 따라 허용되는 작업이 결정됩니다. REST API는 기본적으로 많은 작업을 허용합니다. 예를 들어, 기본적으로 모든 문자열을 검색할 수 있습니다. REST API의 경우 동작을 해제해야 하는 경우에만 특성이 필요할 수 있습니다.
{
"name": "hotels-quickstart",
"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.lucene"},
{"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},
{"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},
{"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}
]
}
]
}
문서 로드
인덱스 만들기 및 로드는 별도의 단계입니다. Azure AI 검색에서 인덱스에는 검색 가능한 모든 데이터가 포함되어 있으며 검색 서비스에서 실행되는 쿼리가 있습니다. REST 호출의 경우 데이터는 JSON 문서로 제공됩니다. 이 작업에는 문서- 인덱스 REST API를 사용합니다.
docs 컬렉션 및 index 작업을 포함하도록 URI가 확장됩니다.
다음 예제를 붙여넣어 JSON 문서를 검색 인덱스로 업로드합니다.
### Upload documents POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "value": [ { "@search.action": "upload", "HotelId": "1", "HotelName": "Stay-Kay City Hotel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.", "Category": "Boutique", "Tags": [ "pool", "air conditioning", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1970-01-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "677 5th Ave", "City": "New York", "StateProvince": "NY", "PostalCode": "10022", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "2", "HotelName": "Old Century Hotel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.", "Category": "Boutique", "Tags": [ "pool", "free wifi", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1979-02-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "140 University Town Center Dr", "City": "Sarasota", "StateProvince": "FL", "PostalCode": "34243", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "3", "HotelName": "Gastronomic Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.", "Category": "Resort and Spa", "Tags": [ "air conditioning", "bar", "continental breakfast" ], "ParkingIncluded": true, "LastRenovationDate": "2015-09-20T00:00:00Z", "Rating": 4.80, "Address": { "StreetAddress": "3393 Peachtree Rd", "City": "Atlanta", "StateProvince": "GA", "PostalCode": "30326", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "4", "HotelName": "Sublime Palace Hotel", "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.", "Category": "Boutique", "Tags": [ "concierge", "view", "24-hour front desk service" ], "ParkingIncluded": true, "LastRenovationDate": "1960-02-06T00:00:00Z", "Rating": 4.60, "Address": { "StreetAddress": "7400 San Pedro Ave", "City": "San Antonio", "StateProvince": "TX", "PostalCode": "78216", "Country": "USA" } } ] }요청 보내기를 선택합니다. 몇 초 후에 인접한 창에 HTTP 201 응답이 표시됩니다.
207이 표시될 경우 하나 이상의 문서를 업로드하지 못했습니다. 404가 표시될 경우 요청의 헤더 또는 본문에 구문 오류가 있습니다.
/docs/index를 포함하도록 엔드포인트를 변경했는지 확인합니다.
쿼리 실행
이제 문서가 로드되었으므로 문서 - 게시물 검색(REST)을 사용하여 문서에 대한 쿼리를 실행할 수 있습니다.
/docs/search 연산자를 사용하여 지정된 쿼리 식을 포함하도록 URI가 확장됩니다.
다음 예제를 붙여넣어 검색 인덱스를 쿼리합니다. 그런 다음, 요청 보내기를 선택합니다. 텍스트 검색 요청에는 항상
search매개 변수가 포함됩니다. 이 예제에는 텍스트 검색을 특정 필드로 제한하는 선택적searchFields매개 변수가 포함되어 있습니다.### Run a query POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "search": "lake view", "select": "HotelId, HotelName, Tags, Description", "searchFields": "Description, Tags", "count": true }인접한 창에서 응답을 검토합니다. 인덱스에서 찾은 일치 항목 수를 나타내는 개수, 관련성을 나타내는 검색 점수 및
select문에 나열된 각 필드의 값이 있어야 합니다.{ "@odata.context": "https://my-demo.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)", "@odata.count": 1, "value": [ { "@search.score": 0.6189728, "HotelId": "4", "HotelName": "Sublime Palace Hotel", "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.", "Tags": [ "concierge", "view", "24-hour front desk service" ] } ] }
인덱스 속성 가져오기
통계 가져오기를 사용하여 문서 개수와 인덱스 크기를 쿼리할 수도 있습니다.
다음 예제를 붙여넣어 검색 인덱스를 쿼리합니다. 그런 다음, 요청 보내기를 선택합니다.
### Get index statistics GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}}응답을 검토합니다. 이 작업은 인덱스 스토리지에 대한 세부 정보를 쉽게 가져올 수 있는 방법입니다.
{ "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics", "documentCount": 4, "storageSize": 34707, "vectorIndexSize": 0 }
리소스 정리
본인 소유의 구독으로 이 모듈을 진행하고 있는 경우에는 프로젝트가 끝날 때 여기에서 만든 리소스가 계속 필요한지 확인하는 것이 좋습니다. 계속 실행되는 리소스에는 요금이 부과될 수 있습니다. 리소스를 개별적으로 삭제하거나 리소스 그룹을 삭제하여 전체 리소스 세트를 삭제할 수 있습니다.
가장 왼쪽 창의 모든 리소스 또는 리소스 그룹 링크를 사용하여 포털에서 리소스를 찾고 관리할 수 있습니다.
이 DELETE 명령을 사용해 볼 수도 있습니다.
### Delete an index
DELETE {{baseUrl}}/indexes/hotels-quickstart?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
다음 단계
이제 REST 클라이언트에 익숙해지고 Azure AI 검색에 대한 REST 호출을 수행했으므로 벡터 지원을 보여 주는 또 다른 빠른 시작을 시도해 보세요.