API 버전 비교

대부분의 API 메서드의 경우 요청 매개변수와 응답 본문은 v1와 v2가 다릅니다. v2 API에서 지원하는 작업을 수행하는 데 사용할 수 있는 동등하거나 대체 가능한 v1 메서드에 대해 알아보세요.

비교 정보는 최신 버전의 v1 API(버전 2019-04-30)를 사용한다고 가정하고 이를 최신 버전의 v2 API(버전 2020-08-30)와 비교한 내용입니다.

환경

v2에는 환경이라는 개념이 없습니다. 규모 및 인덱스 용량과 같은 배포 세부 정보는 서비스 요금제 유형에 따라 관리됩니다. v2에서는 컬렉션이 프로젝트 단위로 구성됩니다. 다양한 유형의 프로젝트를 만들어 프로젝트에 추가하는 컬렉션에 기본 구성 설정을 적용할 수 있습니다.

v2 환경 메서드에 대한 v1에 해당하는 메서드가 없습니다. 그러나 다음 표에는 해당 v2 메서드와 유사한 기능을 하는 v1 메서드가 나와 있습니다. 각 메서드에 대해 반환되는 지원되는 매개변수와 응답 본문도 다릅니다.

환경 API 작업 지원 세부 정보
조치 v1 API 관련 v2 API
환경 작성 POST /v1/environments POST /v2/projects
환경 나열 GET /v1/environments GET /v2/projects
환경 정보 얻기 GET /v1/environments/{environment_id} GET /v2/projects/{project_id}
환경 업데이트 PUT /v1/environments/{environment_id} POST /v2/projects/{project_id}
v2에서는 PUT 대신 POST 를 사용합니다.
환경 삭제 DELETE /v1/environment/{environment_id} DELETE /v2/projects/{project_id}
컬렉션 전체에 걸쳐 필드 나열 GET /v1/environments/{environment_id}/fields GET /v2/projects/{project_id}/fields

구성

v2 API에는 구성 전용 엔드포인트가 없습니다. 대신 프로젝트, 컬렉션 및 쿼리에 대한 구성 설정은 해당 개체에 대한 API에서 직접 지정합니다. v1에서 사용할 수 있는 모든 구성 매개변수를 v2에서 사용할 수 있거나 적용할 수 있는 것은 아닙니다.

v1 구성 API 에서 구성 개체를 지정하는 데 사용되는 JSON 개체에는 다른 v2 엔드포인트와 다른 형식으로 사용 가능하거나 v2에서 사용할 수 없는 여러 매개 변수가 포함되어 있습니다. 다음 표는 v2에서 관련 파라미터를 찾는 방법을 설명합니다.

v2에서는 v1에서와 같이 수집 프로세스 중에 문서 변환을 사용자 지정할 수 없습니다.

구성 설정 세부 정보
v1 구성 매개변수 v2 API
"conversions.html": { ... } 사용할 수 없음
"conversions.image_text_recognition": { ... } API에서는 사용할 수 없습니다. 그러나 제품 사용자 인터페이스에서 컬렉션에 대해 광학 문자 인식(OCR)을 활성화하여 이미지에서 텍스트를 추출할 수 있습니다. OCR은 다른 이점도 있습니다. 예를 들어, 문서의 한 페이지를 처리할 수 없는 경우 OCR은 해당 페이지를 이미지로 변환하고 스캔하여 문서가 성공적으로 업로드되었는지 확인합니다.
"conversions.json_normalizations": { ... } 컬렉션 API 로 이동했습니다.
"conversions.pdf": { ... } 사용할 수 없습니다. PDF의 이미지에서 텍스트를 추출하기 위해 특수 매개변수를 사용한 경우, 대신 PDF가 포함된 컬렉션에 대해 제품 사용자 인터페이스에서 광학 문자 인식(OCR)을 사용하도록 설정하세요.
"conversions.segment": { ... } 프로그래밍 방식으로 사용할 수 없습니다. 제품 사용자 인터페이스에서 subtitle 과 같은 SDU 생성 필드가 발생할 때마다 문서를 분할할 수 있습니다.
segment_metadata 개체와 parent_id, id 및 total_segments 정보는 v2에서 사용할 수 없습니다. metadata.parent_document_id 필드를 사용하여 여러 문서 세그먼트의 공통 부모를 찾을 수 있습니다.
"conversions.word": { ... } 사용할 수 없음
"enrichments": { ... }

/v2/projects/{project_id}/enrichments, /v2/projects/{project_id}/collections/{collection_id}
인라이센싱 API를 사용하여 기존 인라이센싱을 탐색하세요. 컬렉션 API를 사용하여 컬렉션의 필드에서 활성화된 보강 기능을 확인하고 변경할 수 있습니다.
생성하는 프로젝트 유형에 따라 기본적으로 일부 기능이 서비스에 적용됩니다. 자세한 내용은 기본 프로젝트 설정.
을 참조하세요 The version of the Entities enrichment that is available in v2 doesn't include the disambiguation field, which in v1 contains the disambiguation information for the entity and includes the entity subtype information.
다음 보강 기능은 v2:

  • 카테고리
  • 개념
  • 감정
  • 관계
  • 의미적 역할
  • 엔티티의 감정
  • 키워드의 감정입니다
"normalizations": [ ... ] 컬렉션 API 로 이동했습니다.
"source": { ... } 사용할 수 없습니다. 사용자 인터페이스를 통해 외부 데이터 소스에 대한 연결을 구성합니다. 자세한 내용은 컬렉션 만들기 를 참조하세요.

콜렉션

컬렉션 API 지원 세부 정보
조치 v1 API v2 API
콜렉션 작성 POST /v1/environments/{environment_id}/collections POST /v2/projects/{project_id}/collections
지원되는 파라미터와 응답은 두 버전 간에 차이가 있습니다. 수집 노트 를 참조하세요.
콜렉션 나열 GET /v1/environments/{environment_id}/collections GET /v2/projects/{project_id}/collections
v2에서는 각 컬렉션의 컬렉션 ID와 이름만 목록에 반환됩니다. 각 컬렉션에 대한 자세한 정보를 반환하려면 Get collection 메서드를 사용해야 합니다.
컬렉션 세부 정보 보기 GET /v1/environments/{environment_id}/collections/{collection_id} GET /v2/projects/{project_id}/collections/{collection_id}
컬렉션 노트 를 참조하세요.
컬렉션 업데이트 PUT /v1/environments/{environment_id}/collections/{collection_id} POST /v2/projects/{project_id}/collections/{collection_id}
컬렉션 삭제 DELETE /v1/environments/{environment_id}/collections/{collection_id} DELETE /v2/projects/{project_id}/collections/{collection_id}
v2에서는 status 필드가 응답에 반환되지 않습니다.
목록 수집 필드 GET /v1/environments/{environment_id}/컬렉션/{collection_id}/필드
v1는 컬렉션별 필드를 나열합니다.		 GET /v2/projects/{project_id}/fields
v2는 대신 프로젝트별 필드를 나열합니다. collection_ids 매개 변수와 함께 단일 컬렉션 ID를 전달하여 단일 컬렉션에서 필드를 가져올 수 있습니다.

컬렉션 API 참고 사항

다음 표는 v1와 v2 컬렉션 API 간의 중요한 차이점을 보여줍니다.

컬렉션 API 참고 사항
메소드 참고
콜렉션 작성 v2 응답에는 status 및 configuration_id 필드가 포함되지 않습니다. 문서 상세정보 가져오기 메서드를 사용하여 특정 문서의 상태 정보를 얻을 수 있습니다.
disk_usage, training_status 및 crawl_status 개체가 v2에서 응답 본문에 없습니다. document_counts 개체가 현재 v2의 응답 본문에 없습니다. 교육 상태는 Get project 메서드 응답으로 반환됩니다. 다른 정보는 v2에서 사용할 수 없습니다. v2에서 선택적 enrichments 개체를 지정하여 컬렉션의 문서에 적용할 보강 기능을 정의할 수 있습니다.
컬렉션 세부 정보 보기 v2 응답에는 status 및 configuration_id 필드가 포함되지 않습니다. 문서 상세정보 가져오기 메서드를 사용하여 특정 문서의 상태 정보를 얻을 수 있습니다.
document_counts, disk_usage, training_status 및 crawl_status 개체가 v2에서 응답 본문에 없습니다. 교육 상태는 Get project 메서드 응답으로 반환됩니다. 다른 정보는 v2에서 사용할 수 없습니다. 예를 들어, 컬렉션의 문서 수를 가져올 수 없으며 v2에서 외부 데이터 소스에 연결되는 컬렉션의 크롤링 상태를 가져올 수 없습니다. v2에서 컬렉션에 적용된 강화에 대한 정보를 얻을 수 있습니다.
컬렉션 업데이트 v2는 PUT 대신 POST 을 사용합니다. v2에서 선택 사항인 enrichments object를 지정하여 컬렉션의 문서에 적용되는 강화 기능을 업데이트할 수 있습니다.
v2 응답에는 status 및 configuration_id 필드가 포함되지 않습니다.

쿼리 수정

프로그래밍 방식으로 토큰화를 구성하기 위해 v1에서 사용할 수 있었던 방법은 v2 API에서 지원되지 않습니다.

쿼리 수정 API 지원 세부 정보
v1 API v2 API
토큰화 사전 API 사용할 수 없습니다.
확장 v1 API 확장 v2 API
중단어 v1 API 중단어 v2 API

문서

문서 API 지원 세부 정보
조치 v1 API v2 API
문서 목록 v1 API에서는 사용할 수 없습니다 GET /v2/projects/{project_id}/collections/{collection_id}/documents
문서 작성 POST /v1/environments/{environment_id}/collections/{collection_id}/documents POST /v2/projects/{project_id}/collections/{collection_id}/documents
v1와 달리 v2 응답에는 알림 객체가 포함되지 않습니다. 그러나 v2에서 문서 세부정보 가져오기 방법을 사용하여 통지 정보를 얻을 수 있습니다.
문서 업데이트 POST /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} POST /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
분할된 문서를 업데이트하면 모든 문서 세그먼트가 덮어씌워집니다.
문서 세부 정보 보기 GET /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} GET /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
In v2에는 다음과 같이 입력합니다, statusDescription 이 없습니다. v2에는 수집 중에 생성된 하위 문서와 관련된 모든 알림에 대한 정보가 포함된 children 개체가 있습니다.
문서 삭제 DELETE /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} DELETE /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
업로드된 문서의 세그먼트는 개별적으로 삭제할 수 없습니다. 세그먼트 결과의 parent_document_id를 포함하는 DELETE 요청으로 모든 세그먼트를 삭제합니다.

v2에서는 v1에서는 사용할 수 없는 X-Watson-Discovery-Force 이라는 사용자 지정 헤더를 도입합니다. 여러 컬렉션에서 공유되는 데이터에 대해 작업을 수행할 때 헤더를 포함해야 각 컬렉션에서 작업을 수행하려는 것을 나타낼 수 있습니다. 헤더를 포함하지 않으면 403 오류가 반환됩니다.

컬렉션에 추가되는 JSON 파일의 필드는 수집 중에 v1과 v2 간에 다르게 변환됩니다. JSON 파일이 v2 인덱스에 저장되는 방식에 대한 자세한 내용은 JSON 파일 를 참조하세요.

쿼리

문서 API 지원 세부 정보
조치 v1 API v2 API
컬렉션 쿼리 GET 또는 POST 요청을 지원합니다.
GET 또는 POST /v1/environments/{environment_id}/컬렉션/{collection_id}/쿼리		 프로젝트를 쿼리합니다. 단일 컬렉션을 지정하려면 {collection_id} 매개변수를 포함하세요. POST 요청만 지원합니다.
POST /v2/projects/{project_id}/query
다중 콜렉션을 조회합니다. GET 또는 POST /v1/environments/{environment_id}/query POST /v2/projects/{project_id}/query
시스템 공지사항 조회 GET /v1/environments/{environment_id}/컬렉션/{collection_id}/notices GET /v2/projects/{project_id}/collections/{collection_id}/notices
여러 수금 시스템 통지 조회 GET /v1/environments/{environment_id}/notices GET /v2/projects/{project_id}/notices
자동 완성 제안 받기 /v1/environments/{environment_id}/컬렉션/{collection_id}/자동완성 GET /v2/projects/{project_id}/자동완성
쿼리 노트 를 참조하세요.

생성하는 프로젝트 유형에 따라 일부 쿼리 결과 구성이 기본적으로 서비스에 적용됩니다. 자세한 내용은 기본 프로젝트 설정 를 참조하세요.

쿼리 노트

  • v2 쿼리는 프로젝트의 모든 컬렉션에서 결과를 반환합니다. 프로젝트 내에서 특정 컬렉션만 사용하도록 쿼리를 제한하려면 collection_ids 쿼리 매개변수를 사용합니다. 하나의 v2 쿼리 요청으로 서로 다른 프로젝트에 추가된 여러 컬렉션을 쿼리할 수 없습니다.

  • v2 결과에는 confidence 필드가 포함되지만 score 필드는 포함되지 않습니다.

    신뢰도 점수는 v1에서 점수 정보를 대체했지만 이전 버전과의 호환성을 위해 점수는 그대로 유지되었습니다. v2에서는 신뢰도 필드만 반환됩니다.

  • v2로 쿼리를 제출하려면 GET 호출 대신 POST 호출을 사용합니다.

  • v1 쿼리는 많은 매개변수를 허용합니다. 쿼리 매개변수 비교 테이블은 v1 매개변수를 v2 매개변수에 매핑합니다.

    쿼리 매개변수 비교
    v1 매개변수 v2 매개변수 참고
    해당사항 없음 collection_ids 컬렉션 ID를 지정하려면 v2에서 이 파라미터를 사용합니다.
    필터 필터 표현 언어가 동일합니다.
    조회 조회 표현 언어가 동일합니다.
    natural_language_query natural_language_query 참고사항이 없습니다.
    passages passages 구절 형식이 변경되어 v2에서 개선되었습니다. passages:true 매개 변수가 passages.enable:true 로 변경되었습니다. count, characters, fields 옵션 외에도 문서 품질에 따라 문서 순위를 매긴 다음 문서별로 가장 높은 순위에 있는 구절을 반환하는 per_document 을 지정할 수 있습니다. find_answers 을 지정하여 쿼리에 대한 간결한 답변이 포함된 구절별 답변 개체를 반환할 수도 있습니다.
    집계 집계 표현 언어가 동일합니다.
    수 수 참고사항이 없습니다.
    오프셋 오프셋 참고사항이 없습니다.
    리턴 리턴 참고사항이 없습니다.
    정렬 정렬 참고사항이 없습니다.
    강조표시 강조표시 passages.enabled 및 passages.per_document 가 true 인 경우 하이라이트 대신 각 문서에 대한 구절이 반환됩니다.
    맞춤법_제안 맞춤법_제안 참고사항이 없습니다.
    중복 제거하다 해당사항 없음 v2 에서는 지원되지 않습니다.
    similar similar v2에서 형식이 변경되었습니다. similar:true 매개 변수가 similar.enable:true 로 변경되었습니다. document_ids 및 fields 매개 변수가 문자열에서 문자열 배열로 변경되었습니다. document_ids 매개 변수는 이제 enabled 이 참인 경우 필수입니다.
    편향 해당사항 없음 v2 에서는 지원되지 않습니다.

훈련 데이터

v1 트레이닝 데이터 API를 사용하여 두 개의 관련 오브젝트로 작업할 수 있습니다:

  • 학습된 쿼리
  • 쿼리 훈련에 사용되는 예제

이 두 개체는 v1에 별도의 API 엔드포인트가 있습니다. v2에서는 각 쿼리를 학습하는 데 사용되는 예제가 쿼리와 함께 제공되며, 하나의 엔드포인트만 학습 데이터로 작업하는 데 사용됩니다.

예를 들어 학습된 쿼리와 해당 학습 예제 문서를 v2에 추가하려면 POST /v2/projects/{project_id}/training_data/queries 요청을 사용하여 쿼리와 모든 예제를 한 호출의 페이로드에 전달합니다. 마찬가지로 v2의 트레이닝 세트에서 하나의 예제를 업데이트하려면 쿼리와 수정된 예제(다른 모든 예제와 함께)를 v2 업데이트 엔드포인트에 전달해야 합니다. v1에서 예제 정보를 업데이트하려면 업데이트 예제 엔드포인트를 사용하여 하나의 예제만 수정합니다.

v1와 v2의 또 다른 중요한 차이점은 v1에서는 학습된 모델이 특정 컬렉션과 연관되어 있다는 점입니다. v2에서 학습된 모델은 프로젝트와 연결됩니다. 프로젝트 내 여러 컬렉션의 데이터를 사용하여 연관성 모델을 학습시킬 수 있습니다. v2에서 교육 예제를 만들거나 업데이트하는 경우, API는 문서가 저장된 컬렉션에 대해 collection_id 을 요구합니다.

트레이닝 데이터 API 지원 세부 정보
조치 v1 API v2 API
학습 데이터 나열 GET /v1/environments/{environment_id}/collections/{collection_id}/training_data GET /v2/projects/{project_id}/training_data /queries
학습 데이터에 쿼리 추가 POST /v1/environments/{environment_id}/collections/{collection_id}/training_data POST /v2/projects/{project_id}/training_data /queries
모든 교육 데이터 삭제 DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data DELETE /v2/projects/{project_id}/training_data /queries
쿼리에 대한 세부 정보 보기 GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} GET /v2/projects/{project_id}/training_data /queries/{query_id}
학습 데이터 쿼리 삭제 DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} DELETE /v2/projects/{project_id}/training_data /queries/{query_id}
학습 데이터 쿼리에 대한 예제 나열 GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples GET /v2/projects/{project_id}/training_data /queries/{query_id}
예제는 쿼리와 함께 반환되는 목록에 있습니다.
학습 데이터 쿼리에 예제 추가 POST /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples POST /v2/projects/{project_id}/training_data /queries/{query_id}
v2에서 교육 쿼리 만들기 방법을 사용하고 쿼리를 만들 때 모든 예제를 전달합니다. 그렇지 않으면 업데이트 API를 사용하세요.
학습 데이터 쿼리 예제 삭제 DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} POST /v2/projects/{project_id}/training_data/ queries/{query_id}
v2 트레이닝_데이터 업데이트 방법을 사용하세요.
라벨 또는 상호 참조 변경(예 PUT /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} POST /v2/projects/{project_id}/training_data/ queries/{query_id}
v2 트레이닝_데이터 업데이트 방법을 사용하세요.
학습 데이터 예제에 대한 자세한 내용 보기 GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} 사용할 수 없습니다. 모든 예제 읽기 호출을 사용하여 쿼리와 관련된 모든 예제를 가져오고 반환된 목록에서 필요한 예제를 찾습니다.

사용자 데이터

사용자 데이터 API는 v2과 v1에서 동일합니다.

사용자 데이터 API 지원 세부 정보
조치 v1 API v2 API
삭제 DELETE /v1/user_data DELETE /v2/user_data
v1와 유사합니다. customer_id 를 사용하여 해당 고객 ID와 연결된 데이터를 삭제합니다.

이벤트 및 피드백

v1 이벤트 및 피드백 API(/v1/events)는 v2에서 사용할 수 없습니다.

신임 정보

v1 자격 증명 API(/v1/environments/{environment_id}/credentials)는 v2에서 사용할 수 없습니다. 이 기능은 v2 제품 사용자 인터페이스에서 사용할 수 있습니다.

상태 코드

거의 모든 API 메서드에서 v2 요청에 대해 반환되는 상태 코드는 v1 요청에 대해 반환되는 상태 코드와 다릅니다.