다양한 어휘지식을 통합한 WiseWordNet 어휘 지식베이스에 기반하여 어휘 간 거리 정보를 분석하는 기술로서 입력된 여휘간 유사도 결과를 제공합니다. 어휘 간 유사도 분석 API는 HTTP 기반의 REST API 인터페이스로 JSON 포맷 기반의 입력 및 출력을 지원하며 ETRI에서 제공하는 API Key 인증을 통해 사용할 수 있는 Open API입니다.
기술명 | API명 | 1일 허용량 |
---|---|---|
어휘관계 분석 기술 |
|
5,000건/일 |
어휘 간 유사도 분석 API는 REST API이며, 어휘 간 유사도 분석을 수행할 2개의 어휘 데이터를 HTTP 통신으로 ETRI Open API 서버에 전달하면 됩니다. 서버가 제공하는 REST API의 URI는 다음과 같으며 POST 방식으로 호출해야 합니다.
HTTP 요청으로 어휘 간 유사도 분석을 요청할 때 사전 준비 사항에서 발급받은 API Key 정보를 요청하는 본문에 포함시켜야 합니다. 다음은 HTTP 요청 메시지 예입니다.
[HTTP Request Body] { "request_id": "reserved field", "access_key": “YOUR_ACCESS_KEY”, "argument": { “first_word”: “FIRST_YOUR_WORD”, “first_sense_id”: “FIRST_WORD_SENSE_ID”, “second_word”: “SECOND_YOUR_WORD”, “second_sense_id”: “SECOND_WORD_SENSE_ID” } }
위와 같은 HTTP 요청을 ETRI Open API 서버로 전달하면 서버는 JSON 형태의 Text 데이터를 HTTP 응답 메시지로 반환합니다. 다음은 HTTP 응답 예제 입니다.
[HTTP Response Header] Access-Control-Allow-Origin:* Connection:close Content-Length:0 Content-Type:application/json; charset=UTF-8 [HTTP Response Body] { "request_id": "reserved field", "result": 0, "return_type": "com.google.gson.internal.LinkedTreeMap", "return_object": {어휘 간 유사도 분석 결과 JSON} }
JSON parsing을 위해 Gson 라이브러리를 사용하여 제공하고 있습니다. Gson 라이브러리에 대한 자세한 설명은 https://github.com/google/gson 에서 확인 하실 수 있습니다.
import java.io.DataOutputStream; import java.io.IOException; import java.io.InputStream; import java.net.HttpURLConnection; import java.net.MalformedURLException; import java.net.URL; import java.util.HashMap; import java.util.Map; import com.google.gson.Gson; public class Example { static public void main ( String[] args ) { String openApiURL = "http://aiopen.etri.re.kr:8000/WiseWWN/WordRel"; String accessKey = "YOUR_ACCESS_KEY"; // 발급받은 API Key String firstWord = "FIRST_WORD"; // 첫번째 어휘 데이터 String firstSenseId = " FIRST_WORD_SENSE_ID"; // 첫번째 어휘 의미코드 String secondWord = "SECOND_WORD"; // 두번째 어휘 데이터 String secondSenseId = "SECOND_WORD_SENSE_ID"; // 두번째 어휘 의미코드 Gson gson = new Gson(); Map<String, Object> request = new HashMap<>(); Map<String, String> argument = new HashMap<>(); argument.put("first_word", firstWord); argument.put("first_sense_id", firstSenseId); argument.put("second_word", secondWord); argument.put("second_sense_id", secondSenseId); request.put("access_key", accessKey); request.put("argument", argument); URL url; Integer responseCode = null; String responBody = null; try { url = new URL(openApiURL); HttpURLConnection con = (HttpURLConnection)url.openConnection(); con.setRequestMethod("POST"); con.setDoOutput(true); DataOutputStream wr = new DataOutputStream(con.getOutputStream()); wr.write(gson.toJson(request).getBytes("UTF-8")); wr.flush(); wr.close(); responseCode = con.getResponseCode(); InputStream is = con.getInputStream(); byte[] buffer = new byte[is.available()]; int byteRead = is.read(buffer); responBody = new String(buffer); System.out.println("[responseCode] " + responseCode); System.out.println("[responBody]"); System.out.println(responBody); } catch (MalformedURLException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } } }
<?php $openApiURL = "http://aiopen.etri.re.kr:8000/WiseWWN/WordRel"; $accessKey = "YOUR_ACCESS_KEY"; $firstWord = "FIRST_WORD"; $firstSenseId = "FIRST_SENSE_ID"; $secondWord = "SECOND_WORD"; $secondSenseId = "SECOND_SECSE_ID "; $request = array( "access_key" => $accessKey, "argument" => array ( "first_word" => $firstWord, "first_sense_id" => $firstSenseId, "second_word" => $secondWord, "second_sense_id" => $secondSenseId ) ); try { $server_output = ""; $ch = curl_init(); $header = array( "Content-Type:application/json; charset=UTF-8", ); curl_setopt($ch, CURLOPT_HTTPHEADER, $header); curl_setopt($ch, CURLOPT_URL, $openApiURL); curl_setopt($ch, CURLOPT_VERBOSE, true); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode ( $request) ); $server_output = curl_exec ($ch); if($server_output === false) { echo "Error Number:".curl_errno($ch)."\n"; echo "Error String:".curl_error($ch)."\n"; } curl_close ($ch); } catch ( Exception $e ) { echo $e->getMessage (); } echo "result = " . var_dump($server_output); ?>
JSON parsing을 위해 jsoncpp 라이브러리를 사용하여 제공하고 있습니다. jsoncpp 라이브러리에 대한 자세한 설명은 https://github.com/open-source-parsers/jsoncpp 에서 확인 하실 수 있습니다.
HTTP 통신을 위해 curl 라이브러리를 사용하여 제공하고 있습니다. curl 라이브러리에 대한 자세한 설명은 https://curl.haxx.se/libcurl 에서 확인 하실 수 있습니다.
컴파일을 위해서는 아래와 같이 추가된 LIB에 대한 옵션을 추가해야 합니다.
g++ (c++파일명) (JSONCPP)/json/json.h (JSONCPP)/json/json-forwards.h (JSONCPP)/jsoncpp.cpp ?I(CURL)/include -lcurl
#include <curl/curl.h> #include <json/json.h> #include <iostream> #include <string> using namespace std; size_t writeDataFunc(void *ptr, size_t size, size_t nmemb, std::string stream); int main() { char* openApiURL = (char*)"http://aiopen.etri.re.kr:8000/WiseWWN/WordRel"; string accessKey = "YOUR_ACCESS_KEY"; string firstWord = "FIRST_WORD"; string firstSenseId = "FIRST_SENSE_ID"; string secondWord = "SECOND_WORD"; string secondSenseId = "SECOND_SENSE_ID"; Json::Value request; Json::Value argument; argument["first_word"] = firstWord; argument["first_sense_id"] = firstSenseId; argument["second_word"] = secondWord; argument["second_sense_id"] = secondSenseId; request["access_key"] = accessKey; request["argument"] = argument; CURL *curl; curl_slist* responseHeaders = NULL; curl = curl_easy_init(); if( curl == NULL ) { cout << "Unable to initialize cURL interface" << endl ; } else { responseHeaders = curl_slist_append( responseHeaders , "Content-Type: application/json; charset=UTF-8" ) ; string requestJson = request.toStyledString(); long statusCode; string response; curl_easy_setopt(curl, CURLOPT_URL, openApiURL); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, responseHeaders ) ; curl_easy_setopt(curl, CURLOPT_TIMEOUT, 5); curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST"); curl_easy_setopt(curl, CURLOPT_POSTFIELDS, requestJson.c_str()); curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writeDataFunc); curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response); curl_easy_perform(curl); curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &statusCode); curl_easy_cleanup(curl); cout << "[responseCode] " << statusCode << endl; cout << "[responBody]" << endl; cout << response << endl; } return 0; } size_t writeDataFunc(void *ptr, size_t size, size_t nmemb, std::string stream) { size_t realsize = size * nmemb; std::string temp(static_cast<const char*>(ptr), realsize); stream.append(temp); return realsize; }
python 3.0을 기준으로 작성되었습니다.
HTTP 통신을 위해 urllib3 라이브러리를 사용하여 제공하고 있습니다. Python 3.0 이하의 버전에서 예제를 실행하기 위해서는 별도로 urllib3의 설치가 필요합니다. 설치에 대한 설명은 https://pypi.python.org/pypi/urllib3 를 참고하시기 바랍니다. urllib3 라이브러리에 대한 자세한 설명은 https://urllib3.readthedocs.io/en/latest/ 에서 확인 하실 수 있습니다.
#-*- coding:utf-8 -*- import urllib3 import json openApiURL = "http://aiopen.etri.re.kr:8000/WiseWWN/WordRel" accessKey = "YOUR_ACCESS_KEY" firstWord = FIRST_WORD' firstSenseId = 'FIRST_SENSE_ID' secondWord = 'SECOND_WORD' secondSenseId = 'SECOND_SENSE_ID' requestJson = { "access_key": accessKey, "argument": { 'first_word': firstWord, 'first_sense_id': firstSenseId, 'second_word': secondWord, 'second_sense_id': secondSenseId } } http = urllib3.PoolManager() response = http.request( "POST", openApiURL, headers={"Content-Type": "application/json; charset=UTF-8"}, body=json.dumps(requestJson) ) print("[responseCode] " + str(response.status)) print("[responBody]") print(str(response.data,"utf-8"))
var openApiURL = 'http://aiopen.etri.re.kr:8000/WiseWWN/WordRel'; var access_key = 'YOUR_ACCESS_KEY'; var firstWord = 'FIRST_WORD'; var firstSenseId = 'FIRSR_SENSE_ID'; var secondWord = 'SECOND_WORD'; var secondSenseId = 'SECOND_SENSE_ID'; var requestJson = { 'access_key': access_key, 'argument': { 'first_word': firstWord, 'first_sense_id': firstSenseId, 'second_word': secondWord, 'second_sense_id': secondSenseId } }; var request = require('request'); var options = { url: openApiURL, body: JSON.stringify(requestJson), headers: {'Content-Type':'application/json; charset=UTF-8'} }; request.post(options, function (error, response, body) { console.log('responseCode = ' + response.statusCode); console.log('responseBody = ' + body); });
어휘 간 유사도 분석 API에 필요한 요청 본문에 다음과 같은 파라미터를 작성해야 합니다.
[HTTP Request Body] { “access_key”: “YOUR_ACCESS_KEY”, “argument”: { “first_word”: “FIRST_YOUR_WORD”, “first_sense_id”: “FIRST_WORD_SENSE_ID”, “second_word”: “SECOND_YOUR_WORD”, “second_sense_id”: “SECOND_WORD_SENSE_ID” } }
다음은 파라미터에 대한 설명입니다.
Field 명 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
access_key | String | ○ | API 사용을 위해 ETRI에서 발급한 사용자 API Key |
argument | Object | ○ | API 사용 요청 시 분석을 위해 전달할 내용 |
first_word | String | ○ | 비교 분석할 어휘 Text 로서 UTF-8 인코딩된 텍스트만 지원 |
first_sense_id | String |
첫 번째 어휘의 의미 코드 2자리 숫자 : 동음이의어 의미코드 4자리 숫자 : 동음이의어 의미코드(2자리)+다의어 의미 코드(2자리) |
|
second_word | String | ○ | 비교 분석 대상 어휘 Text 로서 UTF-8 인코딩된 텍스트만 지원 |
second_sense_id | String |
두 번째 어휘의 의미 코드 2자리 숫자 : 동음이의어 의미코드 4자리 숫자 : 동음이의어 의미코드(2자리)+다의어 의미 코드(2자리) |
어휘 간 유사도 분석 API는 요청된 어휘 간 유사도 분석 결과를 JSON 형태의 Text 데이터로 반환합니다.
다음은 정상적인 요청 처리에 대한 HTTP 응답 예입니다.
[HTTP Response Header] Access-Control-Allow-Origin:* Connection:close Content-Length:0 Content-Type:application/json; charset=UTF-8 [HTTP Response Body] { "request_id": "reserved field", "result": 0, "return_type": "com.google.gson.internal.LinkedTreeMap", "return_object": {어휘 간 유사도 분석 결과 JSON} }
다음은 오류가 발생한 요청 처리에 대한 HTTP 응답 예입니다.
[HTTP Response Header] Access-Control-Allow-Origin:* Connection:close Content-Length:0 Content-Type:application/json; charset=UTF-8 [HTTP Response Body] { "request_id": "reserved field", "result": -1, "reason": {오류 메시지} }
분석된 결과는 다음과 같은 내용이 포함되어 있습니다.
구분 | JSON Key 이름 | 설명 |
---|---|---|
MetaInfo | Title | Open APIs의 타이틀 명 |
Link | 해당 Open APIs를 사용하기 위한 URL 정보 | |
WWN WordRelInfo | FirstWordInfo | 첫 번째 어휘 정보 |
Word | 어휘의 원문자열 | |
HomonymCode | 어휘의 동음이의어 코드 (2자리 숫자) | |
PolysemyCode | 어휘의 다의어 코드 (2자리 숫자) | |
Definition | 의미 정보 | |
POS | 어휘의 품사 명사 : "n" 동사 : "v" |
|
SecondWordInfo | 두 번째 어휘 정보 | |
Word | 어휘의 원문자열 | |
HomonymCode | 어휘의 동음이의어 코드 (2자리 숫자) | |
PolysemyCode | 어휘의 다의어 코드 (2자리 숫자) | |
Definition | 의미 정보 | |
POS | 어휘의 품사 명사 : "n" 동사 : "v" |
|
WordRelInfo | 어휘 간 유사도 분석 정보 | |
ShortedPath | 가장 가까운 연결 어휘 경로 정보 | |
Distance | 어휘 경로 거리 정보 (숫자) | |
Similarity | 어휘 간 거리 유사도 | |
Algorithm | 거리 유사도 알고리즘 | |
SimScore | 거리 유사도 신뢰도 |
언어 분석 API의 오류 코드 목록은 다음과 같습니다.
http status code | result | reason | 설명 |
---|---|---|---|
400 | -1 | Required arguments is empty | 필수 파라미터의 값이 없는 경우 |
400 | -1 | One or more arguments are not valid | 파라미터의 값이 유효하지 않는 경우 |
413 | -1 | Request Entity Too Large | 요청 문장 또는 어휘의 크기가 서버가 처리 할 수 있는 것보다 큰 경우 |
429 | -1 | Too Many Requests | 사용자가 주어진 시간 내에 서버에 너무 많은 요청을 하는 경우 |
404 | -1 | Unknown Handler | 등록되지 않는 서비스를 요청한 경우 |
408 | -1 | Handler Timeout | 서버의 요청 대기가 시간을 초과한 경우 |
500 | -1 | ETRI service server connection refused | ETRI 분석 서버에서 요청을 받지 못하는 경우 |
500 | -1 | ETRI service server is not exists | 수행 가능한 ETRI 분석 서버가 없는 경우 |
500 | -1 | Recipient Failure | ETRI 분석 서버에서 요청을 처리하지 못하는 경우 |
500 | -1 | Unknown ReplyFailure | API 요청에 알 수 없는 내부 오류가 발생한 경우 |
500 | -1 | Unknown Exception | 알 수 없는 내부 오류가 발생한 경우 |