NAVER Cloud Platform API
  • PDF

NAVER Cloud Platform API

  • PDF

概述

支持使用NAVER Cloud Platform提供的服务和解决方案的应用程序接口(API)称为NAVER Cloud Platform API。

本页提供NAVER Cloud Platform的简单描述以及API调用方法。

API以RESTful API方式显现,以XML、JSON格式响应。可根据操作输入参数值进行注册、修改、删除、查询,并可用在服务及运营工具自动化。通过HTTP方式的GET/POST方法调用实现。

如调用失败,则会返回错误代码和消息。

NAVER Cloud Platform API调用步骤

NAVER Cloud Platform的API调用有如下几个步骤。
1. 创建认证密钥
2. API调用
3. 响应处理
4. 错误处理

创建认证密钥

创建NAVER Cloud Platform账户后,一般会发放一个NAVER Cloud Platform API认证密钥。发放的认证密钥可在NAVER Cloud Platform官网[我的页面] > [账户管理] > [认证密钥管理] 中进行确认。除了在创建账户时自动发放的认证密钥外,用户还可以再创建一个,因此可以最多获取两个认证密钥。

参考

如果用户设置“终止使用”或删除认证密钥,则会将其识别为无效密钥。

API认证密钥由Access Key和Secret Key成对组成。一对API认证密钥在认证API时,会直接传递至参数。

  1. NAVER Cloud Platform官网登录。
  2. [我的页面] > [账户管理] > [认证密钥管理] 菜单中,点击“创建新的API认证密钥”按钮。
    • 如果已有创建的认证密钥,则可使用该认证密钥。
  3. 确认API认证密钥管理所发放的Access Key ID和Secret Key。

API调用

AUTHPARAMS

Header Description
x-ncp-apigw-timestamp * 从1970年1月1日00:00:00世界协调时间(UTC)起经过的时间;以毫秒(Millisecond)显示。
* 若与API Gateway服务器时差超过5分钟,视同无效的请求。
x-ncp-iam-access-key * NAVER Cloud Platform门户或Sub Account发放的Access Key ID。
x-ncp-apigw-signature-v2 * 利用与Access Key ID映射的Secret Key对上述示例的Body进行加密的签名
* HMAC加密算法使用HmacSHA256
  • AUTHPARAMS请求示例
curl -i -X GET \
   -H "x-ncp-apigw-timestamp:1505290625682" \
   -H "x-ncp-iam-access-key:D78BB444D6D3C84CA38D" \
   -H "x-ncp-apigw-signature-v2:WTPItrmMIfLUk/UyUIyoQbA/z5hq9o3G8eQMolUzTEa=" \
 'https://example.apigw.ntruss.com/photos/puppy.jpg?query1=&query2'
  • 创建Signature
    • 换行文字使用\n
    • 根据请求创建StringToSign,使用SecretKey进行HmacSHA256算法加密后,再进行Base64编码。
    • 将此值用作 x-ncp-apigw-signature-v2。
请求 StringToSign
GET /photos/puppy.jpg?query1=&query2
x-ncp-apigw-timestamp={timestamp}
x-ncp-iam-access-key={accesskey}
x-ncp-apigw-signature-v2={signature}
GET /photos/puppy.jpg?query1=&query2
{timeStamp}
{accessKey}
  • 请求示例
public String makeSignature() {
	String space = "";					// one space
	String newLine = "\n";					// new line
	String method = "GET";					// method
	String url = "/photos/puppy.jpg?query1=&query2";	// url (include query string)
	String timestamp = "{timestamp}";			// current timestamp (epoch)
	String accessKey = "{accessKey}";			// access key id (from portal or Sub Account)
	String secretKey = "{secretKey}";

	String message = new StringBuilder()
		.append(method)
		.append(space)
		.append(url)
		.append(newLine)
		.append(timestamp)
		.append(newLine)
		.append(accessKey)
		.toString();

	SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256");
	Mac mac = Mac.getInstance("HmacSHA256");
	mac.init(signingKey);

	byte[] rawHmac = mac.doFinal(message.getBytes("UTF-8"));
	String encodeBase64String = Base64.encodeBase64String(rawHmac);

  return encodeBase64String;
}
/*
https://code.google.com/archive/p/crypto-js/
https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/crypto-js/CryptoJS%20v3.1.2.zip
*/

/*
CryptoJS v3.1.2
code.google.com/p/crypto-js
(c) 2009-2013 by Jeff Mott.All rights reserved.
code.google.com/p/crypto-js/wiki/License
*/
<script type="text/javascript" src="./CryptoJS/rollups/hmac-sha256.js"></script>
<script type="text/javascript" src="./CryptoJS/components/enc-base64.js"></script>

function makeSignature() {
	var space = "";				// one space
	var newLine = "\n";				// new line
	var method = "GET";				// method
	var url = "/photos/puppy.jpg?query1=&query2";	// url (include query string)
	var timestamp = "{timestamp}";			// current timestamp (epoch)
	var accessKey = "{accessKey}";			// access key id (from portal or Sub Account)
	var secretKey = "{secretKey}";			// secret key (from portal or Sub Account)

	var hmac = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, secretKey);
	hmac.update(method);
	hmac.update(space);
	hmac.update(url);
	hmac.update(newLine);
	hmac.update(timestamp);
	hmac.update(newLine);
	hmac.update(accessKey);

	var hash = hmac.finalize();

	return hash.toString(CryptoJS.enc.Base64);
}
import sys
import os
import hashlib
import hmac
import base64
import requests
import time

def	make_signature():
	timestamp = int(time.time() * 1000)
	timestamp = str(timestamp)

	access_key = "{accessKey}"				# access key id (from portal or Sub Account)
	secret_key = "{secretKey}"				# secret key (from portal or Sub Account)
	secret_key = bytes(secret_key, 'UTF-8')

	method = "GET"
	uri = "/photos/puppy.jpg?query1=&query2"

	message = method + " " + uri + "\n" + timestamp + "\n"
	+ access_key
	message = bytes(message, 'UTF-8')
	signingKey = base64.b64encode(hmac.new(secret_key, message, digestmod=hashlib.sha256).digest())
	return signingKey
function makeSignature() {
	nl=$'\\n'

	TIMESTAMP=$(echo $(($(date +%s%N)/1000000)))
	ACCESSKEY="{accessKey}"				# access key id (from portal or Sub Account)
	SECRETKEY="{secretKey}"				# secret key (from portal or Sub Account)

	METHOD="GET"
	URI="/photos/puppy.jpg?query1=&query2"

	SIG="$METHOD"' '"$URI"${nl}
	SIG+="$TIMESTAMP"${nl}
	SIG+="$ACCESSKEY"

	SIGNATURE=$(echo -n -e "$SIG"|iconv -t utf8|openssl dgst -sha256 -hmac $SECRETKEY -binary|openssl enc -base64)
}

响应处理

  • 关于服务API调用的相关响应,请参考各服务的API指南。

错误处理

  • 关于服务API调用的相关错误代码 ,请参考各服务的API指南。

通用错误代码

  • 请求参数为Content-type: application/json时(default)
{
   "error":{
      "errorCode":"210",
      "message":"Permission Denied"
   }
}
  • 请求参数为Content-type: application/xml
<?xml version='1.0' encoding='UTF-8' ?>
<Message>
    <error>
        <errorCode>210</errorCode>
        <message>Permission Denied</message>
    </error>
</Message>
HTTP状态代码 错误代码 错误消息 描述
400 100 Bad Request Exception protocol(https), endocing(UTF-8)等Request错误
401 200 Authentication Failed 认证失败
401 210 Permission Denied 无权限
404 300 Not Found Exception 无权限
429 400 Quota Exceeded 超出Quota
429 410 Throttle Limited 超出Rate
429 420 Rate Limited 超出Rate
413 430 Request Entity Too Large 超出请求NTT大小
503 500 Endpoint Error 端点连接错误
504 510 Endpoint Timeout 超出端点连接时间
500 900 Unexpected Error 异常处理失败的错误

支持API与SDK

此NAVER CLOUD PLATFORM API可通过API控制Server、Load Balancer、Auto Scaling、Monitoring、Security、GeoLocation、Hash Filter等功能。API以RESTful API方式提供,并以XML、JSON格式响应。可根据操作输入参数值进行注册、修改、删除、查询,并可用在服务及运营工具自动化。

服务 API SDK
Server Server API ncloud_server.zip
Load Balancer Load Balancer API ncloud_loadbalancer.zip
Auto Scaling Auto Scaling API ncloud_autoscaling.zip
Monitoring Monitoring API ncloud_monitoring.zip
Security Security API ncloud_security.zip
GeoLocation GeoLocation API ncloud_geolocation.zip
CDN+ CDN+ API ncloud_cdn_v2.zip
Cloud DB Cloud DB API ncloud_clouddb_v2.zip
Cloud Outbound Mailer Cloud Outbound Mailer API ncloud_outboundmailer.zip

Ncloud API发布说明

NAVER Cloud Platform的Ncloud API在推出服务之后,也在不断改善服务。

Ncloud API供应版本介绍

目前NAVER Cloud Platform提供以下三种版本的服务。Ncloud API OLD, Ncloud API V1, Ncloud API V2

建议调用提高便捷性的Ncloud API v2版本。Ncloud API OLD与Ncloud API v1版本在经过一段过渡时期后会终止服务。

  • Ncloud API OLD
    :NAVER Cloud Platform在初期提供的,由https://api.ncloud.com/域所开始的API。Ncloud API OLD版本使用的是OAuth认证方式。

  • Ncloud API V1
    :通过改善API管理功能的全新API Gateway,由https://ncloud.apigw.ntruss.com/域所开始的API。从Ncloud API v1版本开始,提供通过API Gateway发放的API Key进行认证的方式。

    :调用Ncloud API v1时,需要API Gateway发放的API Key,为此需要申请API Gateway服务。(此时,由于只发放API Key,不会产生API Gateway的额外费用。))

  • Ncloud API V2
    :Ncloud API v2无需API Key,虽然操作方式和调用方式与Ncloud API v1相同,但因无需申请API Gateway,因此更加便利。

    :由于部分服务必须应用API Key,因此需要根据各服务的API支持明细,决定是否使用API Key。

Ncloud API认证方式

  1. OAuth认证方式

    • Ncloud API OLD版本中使用的方式,系统无需额外保存登录信息,且只有使用加密的认证令牌才允许访问资源。
  2. API Key认证方式

    • API Key认证方式是通过获取各个账户的Key进行认证的方式。API Key可在NAVER Cloud Platform控制台的 API Gateway > API Key 的“创建API Key”菜单中进行创建。

    • Ncloud API v1在API Key认证和调用时,必须包含在报头内。

    • Ncloud API v2在API Key认证或调用时,无需包含在报头内。

进入以前版本的指南

服务 Ncloud API V1 :(API Key认证) Ncloud API V2 :(API Key非认证)
Server 进入 Server API
Load Balancer 进入 Load Balancer API
Auto Scaling 进入 Auto Scaling API
Monitoring 进入 Monitoring API
Security 进入 Security API
GeoLocation 进入 GeoLocation API
CDN 进入 CDN API
Global CDN 进入 Global CDN API
Cloud DB 进入 Cloud DB API
Cloud Outbound Mailer 进入 Cloud Outbound Mailer API

(由于部分服务必须应用API Key,因此需要根据各服务的API支持明细,决定是否使用API Key。)

Ncloud API Fade out主要日程

  • Ncloud API v1将于2019年12月31日终止服务,自2020年1月1日起将无法使用该服务。
  • Ncloud API OLD将于2019年6月30日终止服务,自2019年6月30日起将无法使用该服务。

本文是否有帮助