入門(mén)指南

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

使用AccessToken

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

使用AppID和AppSecret可獲取一個(gè)AccessToken具體步驟請(qǐng)參考《獲取AccessToken》，在后續(xù)數(shù)據(jù)請(qǐng)求的接口中，請(qǐng)求頭字段傳入AccessToken值即可通過(guò)網(wǎng)關(guān)驗(yàn)證。

登錄葛南云平臺(tái)，選擇工程，進(jìn)入【管理】，可查看和獲取工程的AppID和AppSecret。

登錄葛南云平臺(tái)，進(jìn)入【管理后臺(tái)】→【機(jī)構(gòu)配置】，可查看和獲取組織的AppID和AppSecret。

  登錄葛南云平臺(tái)，進(jìn)入【管理后臺(tái)】→【工程管理】→【工程詳情】，可查看和獲取某個(gè)工程的AppID和AppSecret。

使用白名單

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

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

白名單設(shè)置完成后，將AppID作為一個(gè)參數(shù)調(diào)用數(shù)據(jù)獲取接口即可通過(guò)網(wǎng)關(guān)驗(yàn)證，請(qǐng)求參數(shù)支持放到Body和直接拼接到請(qǐng)求地址后兩種形式。

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

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

1. 通過(guò)Maven引用

Maven項(xiàng)目引用以下，在配置文件中輸入以下配置項(xiàng)即可。

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

2. 通過(guò)下載jar包方式引用

           手動(dòng)下載jar包，并且在項(xiàng)目中引用，這里提供3個(gè)必須引用的jar包的下載地址。

            httpclient-4.5.8.jar

     httpcore-4.4.11.jar

     commons-logging-1.2.jar

將上述相關(guān)依賴(lài)包加載進(jìn)項(xiàng)目后，為方便開(kāi)發(fā)，可封裝一個(gè)公共類(lèi)引用相關(guān)資源，處理http請(qǐng)求。

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;
  }
// 初始化連接池，可用于請(qǐng)求HTTP/HTTPS（信任所有證書(shū)）
  static { 
    // 整個(gè)連接池最大連接數(shù)
    cm = getHttpClientConnectionManager(); 
    // 每路由最大連接數(shù)，默認(rèn)值是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;
  }
}