進行鑑別以執行 REST 指令

您進行鑑別以執行 REST 指令的方式視伺服器的設定方式及您要用於執行指令的工具而定。

註：使用 REST 指令時所需的權限與使用 Web 介面時所需的權限相同。如需權限的相關資訊，請參閱角色及許可權。

利用使用者名稱及密碼進行鑑別

進行鑑別以執行 REST 指令的最簡單方式是利用使用者名稱及密碼。例如，如果要使用 curl 程式，則您可以在指令中指定使用者名稱及密碼，如下列程式碼中所示：

curl -k -u jsmith:passwd
  https://myserver.example.com:8443/cli/application/info
  ?application=JPetStore

使用階段作業金鑰進行鑑別

如果要執行 PUT、POST 及 DELETE 方法，部分用戶端程式需要階段作業金鑰來連接伺服器。此階段作業金鑰出現在名為 UCD_SESSION_KEY 的 Cookie 中。用於傳送 User-Agent 標頭以及其餘 REST 指令的用戶端程式，需要此階段作業金鑰。例如，Microsoft Visual Basic For Applications 及物件類型 WinHttp.WinHttpRequest 需要階段作業金鑰。

對於第一個 REST 指令，不論方法類型為何，都不需要階段作業金鑰，因為用戶端程式利用使用者名稱及密碼進行鑑別。對於同一階段作業中的其他 PUT、POST 及 DELETE 指令，用戶端必須提供階段作業金鑰。伺服器會將階段作業金鑰與使用者名稱及密碼相符，因此用戶端不需要再次指定使用者名稱及密碼。

如果要取得階段作業金鑰，用戶端程式先執行帶使用者名稱及密碼的指令。回應標頭包括階段作業金鑰。帶金鑰的標頭通常具有名稱 Set-Cookie 以及與下列範例類似的值：

UCD_SESSION_KEY=6286eb44-b867-5243-875b-e61c5d8b4301;
Expires=Wed, 09-Sep-2082 16:51:45 GMT; Path=/; Secure

用戶端程式必須從此標頭中擷取階段作業金鑰。在上述範例中，階段作業金鑰是 6286eb44-b867-5243-875b-e61c5d8b4301。然後，對於其他 PUT、POST 及 DELETE 指令，請包括下列標頭：

UCD_SESSION_KEY:sessionKey

將階段作業金鑰用於 sessionKey。

註：對於藍圖設計伺服器 API，請改為使用以下程式碼：

UCR_SESSION_KEY:sessionKey

在 Script 及程式中進行鑑別

許多程式設計及 Scripting 語言都可以呼叫 REST 指令。

下列範例是一個 Python Script，該 Python Script 透過將密碼新增至要求標頭進行鑑別。

#!/usr/bin/env python

import urllib2
import json
import base64
import sys

if not len(sys.argv) == 3:
  print 'usage: script <username> <password>'
  exit(1)

username = sys.argv[1]
password = sys.argv[2]

epass = base64.b64encode(username + ':' + password)
print 'base64 encoded: ' + epass
baseUrl = 'ucdeploy.example.org:8443'

url = 'https://' + baseUrl + '/cli/application/info' + '?application=JPetStore'

opener = urllib2.build_opener(urllib2.HTTPHandler)
req = urllib2.Request(url)
req.add_header('Authorization', 'Basic '+epass)
req.get_method = lambda: 'GET'

resp = opener.open(req)
print resp.read()

在 Groovy Script 中進行鑑別

如需在 Groovy Script 中進行鑑別的範例，請參閱下列頁面：http://devblog.laraziosi.org/extensibility/index.php/devops-articles/6-getting-started-with-the-ibm-urbancode-deploy-rest-api-and-groovy

在 Java 類別中進行鑑別

下列 Java™ 程式碼是利用使用者名稱及密碼進行鑑別的簡式範例。該程式碼接受所有憑證，但您可以修改該程式碼，以控制接受哪些憑證。

此範例需要 HttpComponents-Util.jar 及 uDeployRestClient.jar JAR 檔。檔案 HttpComponents-Util.jar 在伺服器安裝目錄的 lib 資料夾中提供。預設伺服器安裝目錄是 /opt/ibm-ucd/server（在 Linux 上）和 C:\Program Files\ibm-ucd\server（在 Windows 上）。檔案 uDeployRestClient.jar 在許多核心外掛程式（例如，UrbanCode Deploy Applications 外掛程式）中提供。

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URI;
import java.net.URISyntaxException;

import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.log4j.Logger;

import com.urbancode.commons.httpcomponentsutil.HttpClientBuilder;

public class RESTExample {

  public static void main(String[] args) {

  // suppress log4j messages from UCD library
  Logger.getRootLogger().setLevel(org.apache.log4j.Level.OFF);

  HttpClientBuilder clientBuilder = new HttpClientBuilder();
  clientBuilder.setUsername("admin");
  clientBuilder.setPassword("admin");

  // for SSL enabled servers, accept all certificates
  clientBuilder.setTrustAllCerts(true); 
  DefaultHttpClient client = clientBuilder.buildClient();

  try {
    HttpGet request = new HttpGet(new URI(
      "https://ucdeploy.example.org:8443/cli/application/info?application=JPetStore"));

    try {
      HttpResponse resp = client.execute(request);
      BufferedReader br = new BufferedReader ( 
        new InputStreamReader(resp.getEntity().getContent()));

      String currentLine = new String();
      while ((currentLine = br.readLine()) != null){
        System.out.print(currentLine);
      }
    } catch (IOException e) {
      e.printStackTrace();
    }
  } catch (URISyntaxException e) {
    e.printStackTrace();
  }

  }

}

匯入伺服器憑證

預設伺服器憑證未簽署。依預設，部分工具不會連接至含有未簽署憑證的伺服器。如果要存取含有自簽憑證的伺服器，則您可以指示工具以不安全的方式進行連接，或者您可以將憑證匯入到您的用戶端中。請遵循下列步驟，將憑證匯入到您的用戶端中：

將伺服器憑證匯出至檔案：
1. 在用於管理 IBM UrbanCode Deploy 伺服器的電腦上，於文字編輯器中開啟 server.xml 檔。依預設，此檔案位於 server_install/opt/tomcat/conf/server.xml 位置。預設伺服器安裝目錄是 /opt/ibm-ucd/server（在 Linux 上）和 C:\Program Files\ibm-ucd\server（在 Windows 上）。
2. 在 server.xml 檔中，尋找下列程式碼行，並記錄 keystoreFile 及 keystorePass 屬性的值：
```
sslProtocol="TLS"
keystoreFile="conf/tomcat.keystore"
keystorePass="changeit" />
```
3. 在指令行視窗中，執行下列指令：
```
keytool -v -list -keystore keyStoreFileName
```
  keytool 應用程式包括在 Java 開發者套件中，不是 IBM UrbanCode Deploy 的一部分。將 server.xml 檔中 keystoreFile 屬性的名稱用於 keyStoreFileName。當指令提示您輸入密碼時，請指定 keystorePass 屬性的值。預設值為 changeit。
4. 從指令的結果中，尋找伺服器的別名。例如，指令的結果可能與下列程式碼類似：
```
Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: server
Creation date: Mar 19, 2014
Entry type: PrivateKeyEntry
```
  在此程式碼中，別名是 server。
5. 執行下列指令，以將憑證匯出至檔案，並再次指定密碼：
```
keytool -exportcert 
  -alias serverAlias 
  -keystore keyStoreFileName 
  -storetype jks 
  -file server.cert
```
  將伺服器的別名用於 serverAlias。
將 server.cert 檔複製到用戶端電腦。
將 server.cert 檔匯入到用戶端電腦的金鑰儲存庫中：
1. 在用戶端電腦上的指令行視窗中，執行下列指令，並指定用戶端上金鑰儲存庫的密碼。預設值為 changeit。
```
jreLocation\jre\bin\keytool.exe -importcert 
  -alias serverAlias
  -file tomcat.cert 
  -storetype jks 
  -keystore jreLocation\jre\lib\security\cacerts
```
  將 JRE 或 JDK 的位置用於 jreLocation。

現在，使用此 JRE 或 JDK 的部分工具會接受伺服器憑證。其他工具（例如，curl）可能仍不接受伺服器憑證，因為該伺服器憑證未簽署。如果要解決此問題，請為伺服器設定已簽署的憑證。

意見