入門指南

葛南云API是針對企業(yè)二次開發(fā)需求封裝的一套應用程序接口，可幫助您在自己的平臺中獲取和使用葛南云平臺數(shù)據(jù)中心的部分數(shù)據(jù)。葛南云API支持AccessToken和白名單兩種網關驗證方式，驗證接口調用是否合法。其中：AccessToken驗證方式免費對外開放；白名單驗證方式為付費功能，使用前請與我司技術支持人員聯(lián)系溝通。

使用AccessToken

每個組織和工程都有一個AppID和AppSecret，組織的AppID和AppSecret權限等級較高，可以調用該組織下任意工程的數(shù)據(jù)，工程的AppID和AppSecret僅能調用該工程的數(shù)據(jù)。

使用AppID和AppSecret可獲取一個AccessToken具體步驟請參考《獲取AccessToken》，在后續(xù)數(shù)據(jù)請求的接口中，請求頭字段傳入AccessToken值即可通過網關驗證。

登錄葛南云平臺，選擇工程，進入【管理】，可查看和獲取工程的AppID和AppSecret。

登錄葛南云平臺，進入【管理后臺】→【機構配置】，可查看和獲取組織的AppID和AppSecret。

  登錄葛南云平臺，進入【管理后臺】→【工程管理】→【工程詳情】，可查看和獲取某個工程的AppID和AppSecret。

使用白名單

通過白名單，用戶可更方便快捷的調用接口，設置白名單后，調用數(shù)據(jù)獲取接口時傳入AppID即可通過網關驗證。另外使用白名單可以對調用IP地址進行限制，即只有該白名單中的網站才能成功發(fā)起調用。

白名單使用前請與我司技術支持人員聯(lián)系，由專業(yè)技術人員協(xié)助開通后，一個AppID最多可設置三個公網IP作為白名單。

白名單設置完成后，將AppID作為一個參數(shù)調用數(shù)據(jù)獲取接口即可通過網關驗證，請求參數(shù)支持放到Body和直接拼接到請求地址后兩種形式。

開發(fā)環(huán)境準備（以Java為例）

Java環(huán)境下需要安裝引用一些必備的依賴包，可采用通過Maven引用和通過下載引用兩種方式加載。

1. 通過Maven引用

Maven項目引用以下，在配置文件中輸入以下配置項即可。

    <dependency>
     <groupId>org.apache.httpcomponents</groupId>
     <artifactId>httpmime</artifactId>
     <version>4.5.8</version>
    </dependency>

2. 通過下載jar包方式引用

           手動下載jar包，并且在項目中引用，這里提供3個必須引用的jar包的下載地址。

            httpclient-4.5.8.jar

     httpcore-4.4.11.jar

     commons-logging-1.2.jar

將上述相關依賴包加載進項目后，為方便開發(fā)，可封裝一個公共類引用相關資源，處理http請求。

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.methods.HttpRequestBase;
import org.apache.http.config.SocketConfig;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;
// HttpClient 連接池
public class HttpUtil { 

  private static PoolingHttpClientConnectionManager cm = null;

  public static PoolingHttpClientConnectionManager getHttpClientConnectionManager() {
    if (cm == null) {
      cm = new PoolingHttpClientConnectionManager();
      cm.setMaxTotal(200);
      cm.setDefaultMaxPerRoute(20);
      SocketConfig config = SocketConfig.custom().setSoTimeout(10000).build();
      cm.setDefaultSocketConfig(config);
    }
    return cm;
  }
// 初始化連接池，可用于請求HTTP/HTTPS（信任所有證書）
  static { 
    // 整個連接池最大連接數(shù)
    cm = getHttpClientConnectionManager(); 
    // 每路由最大連接數(shù)，默認值是2
    cm.setMaxTotal(200); 
    cm.setDefaultMaxPerRoute(5);
  }

  public static String postHttp(
    String url,
    Map<String, String> paramMap,
    Map<String, String> headerMap
  ) {
    HttpPost request = new HttpPost(url);
    request.addHeader("Content-Type", "application/x-www-form-urlencoded");
    if (paramMap != null && paramMap.size() > 0) {
      List<NameValuePair> nameValuePairs = covertParams2NVPS(paramMap);
      try {
        request.setEntity(
          new UrlEncodedFormEntity(
            nameValuePairs,
            StandardCharsets.UTF_8.name()
          )
        );
      } catch (UnsupportedEncodingException e) {
        e.printStackTrace();
      }
    }
    if (headerMap != null) {
      for (Entry<String, String> param : headerMap.entrySet()) {
        request.addHeader(param.getKey(), param.getValue());
      }
    }
    return doHttp(request);
  }

  public static String post(
    String url,
    Map<String, String> paramMap,
    Map<String, String> headerMap
  ) {
    return postHttp(url, paramMap, headerMap);
  }

  public static String post(String url, Map<String, String> paramMap) {
    return postHttp(url, paramMap, null);
  }

  public static List<NameValuePair> covertParams2NVPS(
    Map<String, String> params
  ) {
    List<NameValuePair> pairs = new ArrayList<NameValuePair>();
    for (Map.Entry<String, String> param : params.entrySet()) pairs.add(
      new BasicNameValuePair(param.getKey(), param.getValue())
    );
    return pairs;
  }

  private static String doHttp(HttpRequestBase request) {
    CloseableHttpClient httpClient = HttpClients
      .custom()
      .setConnectionManager(cm)
      .build();
    return doRequest(httpClient, request);
  }

  private static String doRequest(
    CloseableHttpClient httpClient,
    HttpRequestBase request
  ) {
    String result = null;
    CloseableHttpResponse response = null;
    try {
      try {
        response = httpClient.execute(request);
        HttpEntity entity = response.getEntity();
        result = EntityUtils.toString(entity, StandardCharsets.UTF_8.name());
        EntityUtils.consume(entity);
      } catch (Exception e) {
        e.printStackTrace();
      }
    } finally {
      if (null != response) try {
        response.close();
      } catch (IOException e) {
        e.printStackTrace();
      }
    }
    return result;
  }
}