ポータルのショートカット NAVERクラウドプラットフォームのマニュアル

AI·NAVER APIリスト

現在提供しているAI·NAVER APIのリストです。AI·NAVER APIを使用する前に次の内容を確認してください。

• アプリケーションの登録およびクライアントアイディとシークレットの値を確認: アプリケーション登録ガイド

• API設定を確認: API設定

• HTTPヘッダにクライアントアイディとシークレットの値さえ転送すれば直ちに呼び出して使用できるオープンAPIで、地図、座標変換、短縮URLを始め、音声認識、機械翻訳、音声合成などのオープンAPIが該当します。

APIの基本

API (Application Programming Interface)

開発者がプログラミング作業の際にオペレーティングシステム、システム、アプリケーション、ライブラリなどを利用して応用プログラムを作成できるようにする様々なインターフェースを合わせていう名称です。(例: Window API, Java API, HTML5 API, Android APIなど)

アプリケーション

アプリケーションはAPIを活用して作られる様々なプログラム結果物です。ここでは、デベロッパーがAI·NAVER APIを活用して作るウェブ、モバイルウェブ、モバイルアプリを指します。AI·Service APIを利用するためにはNAVERクラウドプラットフォームコンソールのAI·Application Service > AI·NAVER API > Applicationメニューでアプリケーション情報を登録しなければなりません。

API認証

APIゲートウェイ

AI·NAVER API(v2)はほとんどhttps://naveropenapi.apigw.ntruss.com/サーバを経由して呼び出します。このサーバがつまりAPIゲートウェイサーバであり、オープンAPI呼び出しが入るとAPI呼び出しが正確なのかを判別し、認証されたユーザーなのか、呼び出し許可量を超えていないのかを確認してから実際各APIサーバを呼び出した後、結果値を返します。呼び出しが間違っている場合、エラーコードとメッセージを返します。

Application認証Key

AI·NAVER APIを利用するために、各アプリケーションごとに'Application認証Key'というClient ID, Client Secretというペアの文字列のキーの発行を受け、これをAPI呼び出しの際に一緒にAPIゲートウェイサーバに転送することによって、認証されたユーザーであることを立証します。

API呼び出し

リクエストURL (Request URL)

AI·NAVER APIを呼び出すためのAPIのウェブアドレス(URL)を意味します。https://naveropenapi.apigw.ntruss.com/サービスタイプ/バージョン/APIタイプの形で構成されています。

リクエスト変数(Request Parameter)

AI·NAVER APIを呼び出す際に一緒にサーバに転送しなければならない値で、各APIの明細を参照し、リクエスト変数名が間違っていたり必須のリクエスト変数が抜けないように注意しなければなりません。

URLエンコーディング

ハングルや特殊文字がリクエスト変数の値に含まれている場合、サーバへ転送する際に値が文字化けするので、指定されたルールに従って文字の値をコードの値に変換して転送しなければなりませんが、それをURLエンコーディングといいます。URLエンコーディングされた値を再び元の値に変換することをURLデコーディングといいます。

HTTP関連用語

メソッド(Method)

HTTPプロトコルでウェブサーバがリクエストとレスポンスデータを転送するにおいて、事前に約束した動作方式であり、W3CではGET, POSTを始め、8種類のメソッドが定義されています。NAVERオープンAPIを呼び出すためにサーバにリクエストを送る際、必ずAPI明細が指定されたメソッドを使ってAPIを呼び出さなければなりません。

HTTPヘッダ

HTTPヘッダにはウェブサーバに送るリクエストとリクエストデータを説明するメタ情報が入っています。つまり、メソッド、リクエストURL、httpプロトコルのバージョンなどの情報であり、これに追加的に指定された名前や値などを転送できます。NAVERオープンAPIは基本的にクライアントアイディとシークレットの値をヘッダに含ませて転送すれば利用できるようになっています。

HTTPステータスコード

サーバにAPIリクエストを送ると、サーバからはAPI呼び出しが正常に行われたのかについてHTTPステータスコードの値とともにレスポンスを送ります。例えば、呼び出しが正常に行われた場合は200, API呼び出しの方法が間違っていてエラーが発生した場合は400, 403, 404, サーバにエラーが発生した場合は500のようなステータスコードを返します。NAVERオープンAPIのエラーコードをご参考ください。

API呼び出しの例題

Java

// Papago SMT API例題
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
public class APIExamTranslate {

    public static void main(String[] args) {
        String clientId = "YOUR_CLIENT_ID";//アプリケーションクライアントアイディの値";
        String clientSecret = "YOUR_CLIENT_SECRET";//アプリケーションクライアントシークレットの値";
        try {
            String text = URLEncoder.encode("お会いできて嬉しいです。", "UTF-8");
            String apiURL = "https://naveropenapi.apigw.ntruss.com/nmt/v1/translation";
            URL url = new URL(apiURL);
            HttpURLConnection con = (HttpURLConnection)url.openConnection();
            con.setRequestMethod("POST");
            con.setRequestProperty("X-NCP-APIGW-API-KEY-ID", clientId);
            con.setRequestProperty("X-NCP-APIGW-API-KEY", clientSecret);
            // post request
            String postParams = "source=ko&target=en&text=" + text;
            con.setDoOutput(true);
            DataOutputStream wr = new DataOutputStream(con.getOutputStream());
            wr.writeBytes(postParams);
            wr.flush();
            wr.close();
            int responseCode = con.getResponseCode();
            BufferedReader br;
            if(responseCode==200) { // 正常な呼び出し
                br = new BufferedReader(new InputStreamReader(con.getInputStream()));
            } else {  // エラー発生
                br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
            }
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = br.readLine()) != null) {
                response.append(inputLine);
            }
            br.close();
            System.out.println(response.toString());
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

エラーコードのリスト

APIを呼び出すと、HTTP Status CodeでAPI処理結果を受信し、HTTP Response Bodyでレスポンスの値を受信します。レスポンスの値はOpenAPIによってXMLまたはJSONの形式になります。従って、APIレスポンス処理の際、まずHTTP Status Codeから正常に処理されたのかを確認し、レスポンスの形式に合わせて結果を構文解析してサービスに利用できます。

• 正常な呼び出し: HTTPステータスコードは200であり、各APIごとに指定されたフォーマットの結果値を受信します。
• 正常でない呼び出し: HTTPステータスコードは400, 500番帯であり、各APIサーバ別のエラーコードとエラーメッセージの値を受信します。

エラー発生の主な原因

エラーメッセージのフォーマット

エラーメッセージのフォーマットはエラーが発生する位置と関係なく同一です。

HTTPレスポンスコード

エラーの性格によってHTTPレスポンスコードは400番帯あるいは500番帯のエラーコードで返されます。

エラーメッセージ

エラーメッセージはXMLまたはJSONのフォーマットで提供され、エラーの内容を含めているerrorMessageとエラーのコードを含めているerrorCodeの2つの要素で構成されます。Accept: text/xmlのような情報が入った場合、XMLの形のエラーメッセージを送り、その他の場合はJSONの形のエラーメッセージを送ります。次はXMLとJSONの形のエラーメッセージの例です。

<?xml version="1.0" encoding="UTF-8"?>
 <result>
    <error>
        <message><![CDATA[Authentication failed (認証に失敗しました。)]]></message>
        <errorCode><![CDATA[024]]></errorCode>
     </error>
 </result>

{
  "error": {
    "errorCode": "300",
    "message": "Not Found Exception"
  }
}