In order to provide detailed descriptions of the various NAVER CLOUD PLATFORM services, and to facilitate use of various APIs, we offer [Manual] and [API reference] separately.

API overview

NAVER CLOUD PLATFORM enables you to control various services such as Server, Load Balancer, Auto Scaling, Monitoring, Security, GeoLocation and Hash Filter with APIs. The APIs are RESTful, and their response format is XML and JSON. You can register, modify, delete, and get data by specifying required parameters, in order to run services and automate operation tools.

Supported APIs

Product API SDK
Server Server API ncloud_server_v2.zip
Load Balancer Load Balancer API ncloud_loadbalancer_v2.zip
Auto Scaling Auto Scaling API ncloud_autoscaling_v2.zip
Monitoring Monitoring API ncloud_monitoring_v2.zip
Security Security API ncloud_security_v2.zip
GeoLocation GeoLocation API ncloud_geolocation_v2.zip
CDN CDN API ncloud_cdn_v2.zip
Cloud DB Cloud DB API ncloud_clouddb_v2.zip

Contents


Preparation

Get authentication keys for your account.

API request

  • An API request message consists of the following:
{API URL}/{Action} + Action parameter + Response format + AUTHPARMS(header)

You can make an API request, using your authentication keys (Access Key ID, Secret Key, and API Key).

Classification Definition
API URL Server
(https://ncloud.apigw.ntruss.com/server/v1/{action})
(https://ncloud.apigw.ntruss.com/server/v2/{action})
Load Balancer
(https://ncloud.apigw.ntruss.com/loadbalancer/v1/{action})
(https://ncloud.apigw.ntruss.com/loadbalancer/v2/{action})
Auto Scaling
(https://ncloud.apigw.ntruss.com/autoscaling/v1/{action})
(https://ncloud.apigw.ntruss.com/autoscaling/v2/{action})
Monitoring
(https://ncloud.apigw.ntruss.com/monitoring/v1/{action})
(https://ncloud.apigw.ntruss.com/monitoring/v2/{action})
Security
(https://ncloud.apigw.ntruss.com/security/v1/{action})
(https://ncloud.apigw.ntruss.com/security/v2/{action})
GeoLocation
(https://ncloud.apigw.ntruss.com/geolocation/v1/{action})
(https://ncloud.apigw.ntruss.com/geolocation/v2/{action})
Hash Filter
(https://ncloud.apigw.ntruss.com/hashfilter/v1/{action})
(https://ncloud.apigw.ntruss.com/hashfilter/v2/{action})
Action Server resource request action (create, delete, get, etc.)
action=createServerInstances
Action parameter serverName=myserver&serverImageProductCode=SPSWLINUX000031
The requested parameter must be requested with URL Encoding.
Action XML and JSON response formats are supported (default: XML)
responseFormatType=xml
AUTHPARAMS Add required keys to the request header (x-ncp-apigw-api-key, x-ncp-apigw-timestamp, x-ncp-iam-access-key, x-ncp-apigw-signature-v1)
  • Process a response of each API request.
    • Check the response format of each API.

Action parameter

Basically, an action parameter consists of a pair of Key and Value. List (List) type parameters are in ListTypeParameterName.N format, while Map List (Map < String, List >) parameters are in ListName.N.ParameterName format. “N” in the formats starts from 1 and cannot exceed 100.

  • General action parameter
&pageNo=1
&serverName=myServer
…
  • List type action parameter
&serverInstanceNoList.1=1
&serverInstanceNoList.2=2
…
  • Map List type action parameter
&loadBalancerRuleList.1.protocolTypeCode=HTTP
&loadBalancerRuleList.1.loadBalancerPort=80
&loadBalancerRuleList.1.serverPort=80
&loadBalancerRuleList.2.l7HealthCheckPath=/l7check.html
&loadBalancerRuleList.1.protocolTypeCode=HTTP
&loadBalancerRuleList.1.loadBalancerPort=81
&loadBalancerRuleList.1.serverPort=81
&loadBalancerRuleList.2.l7HealthCheckPath=/l7check2.html
…

Create AUTHPARAMS

Header Description
x-ncp-apigw-timestamp It is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC.
If the time difference with the APIGW server is more than 5 minutes, the request is considered invalid.
x-ncp-apigw-api-key API key issued by API Gateway (primary key or secondary key)
x-ncp-iam-access-key Access key ID issued by the portal or Sub Account
x-ncp-apigw-signature-v1 Signature used to encrypt the body of the example below with the “secret key” that maps with the “access key ID.”
The HMAC encryption algorithm is HMAC SHA256.
curl -i -X GET \
   -H "x-ncp-apigw-timestamp:1505290625682" \
   -H "x-ncp-apigw-api-key:cstWXuw4wqp1EfuqDwZeMz5fh0epaTykRRRuy5Ra" \
   -H "x-ncp-iam-access-key:D78BB444D6D3C84CA38A" \
   -H "x-ncp-apigw-signature-v1:WTPItrmMIfLUk/UyUIyoQbA/z5hq9o3G8eQMolUzTEo=" \
 'https://ncloud.apigw.ntruss.com/petStore/v1/pets'
  • Create a signature
Request StringToSign
GET /photos/puppy.jpg?query1=&query2
x-ncp-apigw-timestamp={timestamp}
x-ncp-apigw-api-key={apiKey}
x-ncp-iam-access-key={accesskey}
x-ncp-apigw-signature-v1={signature}
GET /photos/puppy.jpg?query1=&query2
{timeStamp}
{apiKey}
{accessKey}

Add a new line with \n.

Create a StringToSign appropriate for your request, encrypt it with your secret key and the HMACSHA256 algorithm and encode it with Base64. Use this value as x-ncp-apigw-signature-v1.

  • Java sample code(v1)
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 apiKey = "{apiKey}";                // api key (from api gateway)
    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(apiKey)
        .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;
}
  • Java sample code(v2)
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;
}
  • JavaScript sample code(v1)
/*
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 apiKey = "{apiKey}";            // api key (from api gateway)
    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(apiKey);
    hmac.update(newLine);
    hmac.update(accessKey);

    var hash = hmac.finalize();

    return hash.toString(CryptoJS.enc.Base64);
}
  • JavaScript sample code(v2)
/*
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);
}
  • Python 3 sample code(v1)
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)

    api_key = "{apiKey}"                    # api key (from api gateway)
    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"
    + api_key + "\n"
    + access_key
    message = bytes(message, 'UTF-8')
    signingKey = base64.b64encode(hmac.new(secret_key, message, digestmod=hashlib.sha256).digest())
    return signingKey
  • Python 3 sample code(v2)
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
  • Bash sample code(v1)
function makeSignature() {
    nl=$'\\n'

    TIMESTAMP=$(echo $(($(date +%s%N)/1000000)))
    APIKEY="{apiKey}"                    # api key (from api gateway)
    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+="$APIKEY"${nl}
    SIG+="$ACCESSKEY"

    SIGNATURE=$(echo -n -e "$SIG"|iconv -t utf8 |openssl dgst -sha256 -hmac $SECRETKEY -binary|openssl enc -base64)
}
  • Bash sample code(v2)
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+="$APIKEY"${nl}
    SIG+="$ACCESSKEY"

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

API response

This section describes API responses.

API response format

Basically, API response data is in XML or JSON format.

  • XML response
<getZoneListResponse>
    <requestId>c385247e-6c76-4b20-ba67-509d5dc95f68</requestId>
    <returnCode>0</returnCode>
    <returnMessage>success</returnMessage>
    <zoneList>
        <zone>
            <zoneNo>2</zoneNo>
            <zoneName>zone2</zoneName>
            <zoneDescription>nang zone</zoneDescription>
        </zone>
        <zone>
            <zoneNo>3</zoneNo>
            <zoneName>zone3</zoneName>
            <zoneDescription>nang zone2</zoneDescription>
        </zone>
    </zoneList>
</getZoneListResponse>
  • JSON response
{
    "getZoneListResponse": {
        "requestId": "b6b9d54f-2770-40bb-a8a9-cc6aa46f75e0",
        "returnCode": 0,
        "returnMessage": "success",
        "zoneList": [{
            "zone": [{
                "zoneNo": 2,
                "zoneName": "zone2",
                "zoneDescription": "nang zone"
            }, {
                "zoneNo": 3,
                "zoneName": "zone3",
                "zoneDescription": "nang zone2"
            }]
        }]
    }
}

Error handling

API errors

If an API request is invalid or an error occurs while processing the request, error information is returned as a response with an HTTP response code other than "200 OK."
The error information consists of a return code and return message , and has CommonResponse data type. All errors are also returned with the name .

  • Sample – user error: HTTP Response Code = 400

    <responseError>
        <returnCode>900</returnCode>
        <returnMessage>
        Required field is not specifie4. location : serverImageProductCode.
        </returnMessage>
    </responseError>
    
  • Sample – authentication error: HTTP Response Code = 401

    <responseError>
        <returnCode>801</returnCode>
        <returnMessage>Signature is invalided</returnMessage>
    </responseError>
    
  • The table below shows the error information sorted by HTTP response code.

HTTP Response Code Return Code Return Message
400 900 - 999 Parameter-related errors
400 1100 BAD REQUEST
400 1400 - 1499 Other errors caused by users
400 10000 - 29999 Other errors caused by users
401 800 - 899 Authentication-related errors
404 1101 NOT FOUND
405 1102 METHOD NOT ALLOWED
500 1000 - 1399 Internal server errors

The table below shows the same error information as the above, but is sorted by return code.

HTTP Response Code Return Message Return Code
401 Authentication-related errors 800 - 899
400 Parameter-related errors 900 - 999
500 Internal server errors 1000 - 1399
400 BAD REQUEST 1100
404 NOT FOUND 1101
405 METHOD NOT ALLOWED 1102
400 Other errors caused by users 1400 - 1499
400 Other errors caused by users 10000 - 29999

API Gateway errors

  • When responseFormatType=xml is set

    <?xml version='1.0' encoding='UTF-8' ?>
    <Message>
      <error>
          <errorCode>210</errorCode>
          <message>Permission Denied</message>
      </error>
    </Message>
    
  • When responseFormatType=json is set

    {
     "error":{
        "errorCode":"210",
        "message":"Permission Denied"
     }
    }
    
  • Error code

HTTP Status Code Error Code Error Message Description
400 100 Bad Request Exception Request errors regarding protocol (https) and encoding (UTF-8).
401 200 Authentication Failed Authentication failed.
401 210 Permission Denied No permissions.
404 300 Not Found Exception No permissions.
429 400 Quota Exceeded Quota exceeded.
429 410 Throttle Limited Rate exceeded.
429 420 Rate Limited Rate exceeded.
413 430 Request Entity Too Large Request entity size exceeded.
503 500 Endpoint Error Endpoint connection error
504 510 Endpoint Timeout Endpoint connection timeout.
500 900 Unexpected Error Exception unhandled.

For more information, refer to “API Request.”

に対する検索結果は~件です。 ""

    に対する検索結果がありません。 ""

    処理中...