無法設定部署錯誤

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

問題

透過 Edge UI 或 Management API 部署 API Proxy 或共用流程修訂版本會失敗，並顯示「Configuration failed」(設定失敗) 錯誤。

錯誤訊息

您會在 Edge UI 中看到錯誤訊息，如下所示：

The revision is deployed, but traffic cannot flow.
com.apigee.kernel.exceptions.spi.UncheckedException{ code = application.bootstrap.FailedToConfigure, message = Configuration failed, associated contexts = []}

以下是在 Edge UI 中觀察到的錯誤訊息範例螢幕截圖：

可能原因

許多原因都可能導致 API Proxy 部署失敗並顯示「設定失敗」錯誤。下表列出導致這類錯誤的常見原因：

原因 說明 適用的疑難排解操作說明
Java 呼叫政策缺少 Java 類別 Java 呼叫政策參照的 JAR 檔案缺少 Java 類別。 Edge Private Cloud 使用者
條件流程中條件使用的運算元不正確 條件中運算子的一或兩側的運算元/運算式無效。
郵件記錄政策中的主機名稱無效 MessageLogging 政策使用的主機名稱無法解析，或是含有不必要的特殊字元。
KeyValueMap Name 無效 API Proxy 的 KeyValueMapOperations 政策中的 KeyValueMap 無效或空白。

常見診斷步驟

  1. 針對您要觀察到的部署錯誤，使用以下 API，取得特定 API Proxy 修訂版本的部署狀態：

    curl -v <management-server-host>:<port#>/v1/runtime/organizations/<org-name>/environments/<env-name>/apis/<apiproxy-name>/revisions/deployments -u <user>

  2. 以下是上述 API 的輸出範例：

    "server" : [ { 
"error" : "com.apigee.kernel.exceptions.spi.UncheckedException{ code = application.bootstrap.FailedToConfigure, message = Configuration failed, associated contexts = []}", 
"status" : "error", 
"type" : [ "message-processor" ], 
"uUID" : "0a20926c-f4bf-401b-af84-05fd84b9f492" 
}, { 
"error" : "com.apigee.kernel.exceptions.spi.UncheckedException{ code = application.bootstrap.FailedToConfigure, message = Configuration failed, associated contexts = []}", 
"status" : "error", 
"type" : [ "message-processor" ], 
"uUID" : "f2ee6ab4-a108-4465-a7ba-b56530d8e3fc" 
}, { 
"error" : "com.apigee.kernel.exceptions.spi.UncheckedException{ code = application.bootstrap.FailedToConfigure, message = Configuration failed, associated contexts = []}", 
"status" : "error", 
"type" : [ "message-processor" ], 
"uUID" : "0f41991e-b310-4e77-aac5-5fdb150ef9f6" 
},

  3. 在部署狀態輸出結果中，每個訊息處理器會顯示錯誤訊息 "Configuration failed"。

  4. 登入任一個訊息處理器並查看記錄 /opt/apigee/var/log/edge-message-processor/logs/system.log。查看 API Proxy 的部署期間是否有任何錯誤。

  5. 視您在郵件處理器記錄中觀察到的錯誤/例外狀況而定，您需要按照適當的疑難排解步驟和解決方法進行。

  6. 以下各節列舉出最常導致部署錯誤「設定失敗」的例外狀況，並提供排解問題的步驟。

原因：Java 呼叫政策中缺少 Java 類別

診斷

  1. 在「訊息處理器」記錄中，如果系統在部署 API Proxy (DeployEvent) 時顯示任何例外狀況，且顯示「Failed to 秘訣 the Java callout Class」訊息 (如下所示)，請繼續步驟 2。如果沒有，請參閱條件流程中條件使用的運算元不正確。

  2. 訊息處理器在部署 API Proxy 時會顯示以下例外狀況：

    2017-10-10 05:02:42,330 Apigee-Main-5 ERROR MESSAGING.CONFIGURATION - MessageProcessorServiceImpl.configure() : error configuring config events [DeployEvent{organization='myorg', application='oauth2', applicationRevision='14', deploymentSpec=basepath=/;env=dev;, deploymentID=null}] 
com.apigee.kernel.exceptions.spi.UncheckedException: Failed to instantiate the JavaCallout Class com.something.apigee.callout.crypto.main.SecretCallout 
at com.apigee.steps.javacallout.JavaCalloutStepDefinition.newInstance(JavaCalloutStepDefinition.java:89) ~[javacallout-1.0.0.jar:na] 
at com.apigee.messaging.runtime.StepDefinition.getStepDefinitionExecution(StepDefinition.java:230) ~[message-processor-1.0.0.jar:na] 
…
<snipped>

  3. 上述例外狀況的錯誤訊息表示 Java Call 類別 com.something.apigee.callout.crypto.main.SecretCallout 無法執行個體化。此錯誤通常發生在 Java 呼叫政策指定的 JAR 檔案中，或其任何相依 JAR 檔案時。

  4. 請檢查 JAR 檔案，其中包含與 com.something.apigee.callout.crypto.main 套件相關的所有類別，並確認缺少特定類別 com.something.apigee.callout.crypto.main.SecretCallout。

解析度

  1. 將缺少的類別新增至特定 JAR 檔案，然後上傳這個 JAR 檔案。
  2. 重新部署 API Proxy。
  3. 在上例中，我們已透過以下方式解決問題：
    1. 在 JAR 檔案中加入缺少的類別 com.something.apigee.callout.crypto.main.SecretCallout。
    2. 上傳更新後的 JAR 檔案，並重新部署 API Proxy。

原因：條件流程中與運算子搭配使用的運算元不正確

診斷

  1. 如果您在訊息處理器記錄檔中看見 com.apigee.expressions.parser.ParseException 在 API Proxy 或共用流程的部署期間 (如下方訊息範例所示)，請繼續執行步驟 2。如果問題則否，請參閱下一個導致「郵件記錄政策中的主機名稱無效」問題。

    錯誤訊息示例

    com.apigee.expressions.parser.ParseException: Both the operands for EQUALS expression should be data expressions

  2. 以下讓我們透過例子來瞭解如何診斷這個問題。

    範例：<Operator> 運算式的運算元應為資料運算式

  3. 訊息處理器在共用流程部署期間會顯示以下例外狀況：

    2017-11-23 09:11:04,498  Apigee-Main-6 ERROR MESSAGING.RUNTIME - AbstractConfigurator.loadXMLConfigurations() : Unable to Load default for path /organizations/myorg/apiproxies/Introspection/revisions/12/sharedflows/default
2017-11-23 09:11:04,499  Apigee-Main-6 ERROR MESSAGING.RUNTIME - Application.sync() :  sync error for Introspection and revision 12
2017-11-23 09:11:04,499  Apigee-Main-6 ERROR MESSAGING.RUNTIME - Application.sync() :  Actual Error
com.apigee.expressions.parser.ParseException: Both the operands for EQUALS expression should be data expressions
    at com.apigee.expressions.parser.ExpressionParser.buildExpressionTree(ExpressionParser.java:337) ~[expressions-1.0.0.jar:na]
    at com.apigee.expressions.parser.ExpressionParser.parse(ExpressionParser.java:24) ~[expressions-1.0.0.jar:na]
    at com.apigee.expressions.parser.ExpressionParser.parseLogicExpression(ExpressionParser.java:28) ~[expressions-1.0.0.jar:na]
    at com.apigee.messaging.runtime.Step.getExpression(Step.java:67) ~[message-processor-1.0.0.jar:na]
    at com.apigee.messaging.runtime.Step.handleAdd(Step.java:58) ~[message-processor-1.0.0.jar:na]
    at com.apigee.messaging.runtime.SharedFlowRuntime.addStep(SharedFlowRuntime.java:81) ~[message-processor-1.0.0.jar:na] … <snipped>

  4. ParseException 中的錯誤訊息「Both the operands for EQUALS expression should be data expressions」表示牽涉到 (=)、不等於 (!=) 或統計資料 (=|) 運算子的條件有問題。

  5. 請在所有條件流程中，查看錯誤訊息中提及的特定運算子的條件，確認是否有任何問題：

    1. 運算子左右兩側的運算式都屬於相同類型。舉例來說，如果運算子左側有字串變數，則右側需要其他字串變數或字串值。
    2. 有效的變數會用於運算子。
    3. 運算子和每個運算式之間留有空格。

  6. 如果不符合上述任一條件，就會取得 ParseException -「Both the operands for EQUALS expression should be data expressions」。

  7. 以下透過例子來瞭解這個問題。這裡有個錯誤條件範例

    <Condition>
           (fault.name = "invalid_access_token") or(fault.name = "ApiKeyNotApproved")
</Condition>

  8. 在本範例中，您可以觀察「or」運算子和下一個條件之間沒有空格。因此，剖析第二個條件時，系統會將第一個運算式做為 EQUALS 運算子的 "or(fault.name")。這不是有效的變數名稱，因此無法視為有效的資料運算式。因此，您會收到以下例外狀況：

    com.apigee.expressions.parser.ParseException: Both the operands for EQUALS expression should be data expressions

解析度

  1. 確保運算子的兩側一律有適當的資料運算式。

  2. 在上述範例中，解析度是為了確保「or」運算子後方有空格，如程式碼片段所述：

    <Condition>
           (fault.name = "invalid_access_token") or (fault.name = "ApiKeyNotApproved")
</Condition>

MessageLogging 政策中的主機名稱無效

診斷

  1. 如下方所示，在「訊息處理者」記錄中，如果 API Proxy 或共用流程部署期間顯示「Invalid HostName」訊息，表示例外，然後繼續執行步驟 2。如果並非如此，請前往下一個原因：Invalid KeyValueMap Name。

    com.apigee.rest.framework.ValidationException: Invalid syslog config: Invalid HostName 'splunkprod.myorg.com/' for Syslog handler

  2. 請參閱下方兩個示例，瞭解如何解決這個問題並解決這個問題。

示例 1：HostName 包含不必要的特殊字元

  1. 訊息處理器在部署 API Proxy 時會顯示以下例外狀況：

      2018-01-20 02:12:13,535 Apigee-Main-3 ERROR MESSAGING.CONFIGURATION - MessageProcessorServiceImpl.configure() : error configuring config events [DeployEvent{organization='myorg', application='providersearch', applicationRevision='4', deploymentSpec=basepath=/;env=prod;, deploymentID=null}] 
  com.apigee.rest.framework.ValidationException: Invalid syslog config: Invalid HostName 'splunkprod.myorg.com/' for Syslog handler 
  at com.apigee.messaging.runtime.destinations.SyslogDestination.<init>(SyslogDestination.java:44) ~[message-processor-1.0.0.jar:na] 
  at com.apigee.messaging.runtime.destinations.SysLoggerFactory.getInstance(SysLoggerFactory.java:39) ~[message-processor-1.0.0.jar:na]
  at com.apigee.messaging.runtime.destinations.DestinationRegistry.newDestination(DestinationRegistry.java:44) ~[message-processor-1.0.0.jar:na] 
  ...<snipped>

  2. 上方的例外狀況代表「Syslog 處理常式的 HostName '<hostname>」導致部署失敗。這表示 MessageLogging 政策中使用的 HostName 是無效的主機名稱。

  3. 仔細檢查「訊息處理者」記錄中的例外狀況後，主機名稱 'splunkprod.myorg.com/'. 結尾處有不必要的特殊字元「/」

  4. 這個不需要的特殊字元是部署錯誤的原因。

解析度

  1. 修改 MessageLogging 政策，移除任何不必要的特殊字元以解決問題。
  2. 在上述範例中，特殊字元「/」已從 MessageLogging 政策中移除。這就解決了這個問題。

示例 2：無法解析的主機名稱

  1. 訊息處理器記錄中有幾行內容顯示已觸發 API Proxy 的部署事件，接著是 API Proxy 部署期間發生例外狀況：

    2017-12-22 00:13:49,057 Apigee-Main-87446 INFO MESSAGING.CONFIGURATION - MessageProcessorServiceImpl.configure() : configuring [DeployEvent{organization='myorg', application='myapi', applicationRevision='42', deploymentSpec=basepath=/;env=dev;, deploymentID=null}] 

2017-12-22 00:13:49,318 Apigee-Main-87446 ERROR c.a.p.h.d.DNSCachedAddress - DNSCachedAddress.refresh() : Unable to resolve host : input-prd.cloud.splunk.com: Name or service not known 

2017-12-22 00:13:49,323 Apigee-Main-87446 ERROR MESSAGING.RUNTIME - AbstractConfigurator.handleUpdate() : Fatal error deploying proxy: {} 
com.apigee.rest.framework.ValidationException: Invalid syslog config: Invalid HostName 'input-prd.cloud.splunk.com' for Syslog handler 
at com.apigee.messaging.runtime.destinations.SyslogDestination.<init>(SyslogDestination.java:44) ~[message-processor-1.0.0.jar:na] 
at com.apigee.messaging.runtime.destinations.SysLoggerFactory.getInstance(SysLoggerFactory.java:39) ~[message-processor-1.0.0.jar:na] 
at com.apigee.messaging.runtime.destinations.DestinationRegistry.newDestination(DestinationRegistry.java:44) ~[message-processor-1.0.0.jar:na] 
at com.apigee.steps.messagelogging.MessageLoggingStepDefinition.populateDestinations(MessageLoggingStepDefinition.java:118) ~[message-logging-1.0.0.jar:na] 
at com.apigee.steps.messagelogging.MessageLoggingStepDefinition.handleAdd(MessageLoggingStepDefinition.java:99) ~[message-logging-1.0.0.jar:na] 
…
<snipped>

  2. 上方的例外狀況代表「Syslog 處理常式的 HostName '<hostname>」導致部署失敗。

  3. 詳閱例外狀況的上述行後，您會發現訊息處理器無法解析 MessageLogging 政策中提供的主機名稱 'input-prd.cloud.splunk.com'。

  4. 如要確認這一點，您可以嘗試連線至訊息記錄政策中使用的主機名稱和通訊埠 #。

    1. 檢查 API Proxy 特定修訂版本中的 MessageLogging 政策，並驗證使用的主機名稱和通訊埠 #。在上述範例中，API Proxy 名稱：myapi，修訂版本：42。

      MessageLogging 政策

        <MessageLogging async="false" continueOnError="false" enabled="true" name="Log-To-Splunk">
      <DisplayName>Log-To-Splunk</DisplayName>
      <Syslog>
          <Message>Message.id = {request.header.id}</Message>
          <Host>input-prd.cloud.splunk.com</Host>
          <Port>2900</Port>
          <Protocol>TCP</Protocol>
          <SSLInfo>
              <Enabled>true</Enabled>
          </SSLInfo>
      </Syslog>
  </MessageLogging>

    2. Telnet 連結至具有特定通訊埠的主機。在這個範例中，我們嘗試過 telnet，但收到的錯誤與「訊息處理器」記錄中顯示的錯誤相同：

      telnet input-prd.cloud.splunk.com 2900 
telnet: input-prd.cloud.splunk.com: Name or service not known 
input-prd.cloud.splunk.com: Host name lookup failure

  5. 這已明確證明無法解析主機名稱。

解析度

  1. 修改 MessageLogging 政策，以便使用有效的主機名稱。

如果問題仍未解決，請參閱「必須收集診斷資訊」一文。

原因：無效的 KeyValueMap 名稱

診斷

  1. 如果「訊息處理者」記錄在部署 API Proxy 或共用流程時，顯示「KeyValueMap name is invalid」(金鑰值對應名稱無效) 例外狀況，請按照下方步驟操作，然後繼續執行步驟 2。如果不是，請參閱必須收集診斷資訊一文。

    com.apigee.rest.framework.ValidationException: Invalid syslog config: Invalid HostName 'splunkprod.myorg.com/' for Syslog handler

  2. 我們來看看示例，瞭解如何解決這個問題並解決這個問題。

  3. 訊息處理者記錄範例顯示「KeyValueMap name is 無效」訊息的例外狀況，導致 API Proxy 部署期間發生錯誤

    2018-02-27 14:14:50,318  Apigee-Main-6 ERROR MESSAGING.RUNTIME - AbstractConfigurator.handleUpdate() : Fatal error deploying proxy: {}
com.apigee.keyvaluemap.KeyValueMapApiException: KeyValueMap name  is invalid
        at com.apigee.keyvaluemap.service.legacy.KeyValueMapServiceImpl.validateMapName(KeyValueMapServiceImpl.java:125) ~[keyvaluemap-1.0.0.jar:na]
        at com.apigee.keyvaluemap.service.legacy.KeyValueMapServiceImpl.createOrUpdateKeyValueMap(KeyValueMapServiceImpl.java:185) ~[keyvaluemap-1.0.0.jar:na]
        at com.apigee.steps.keyvaluemapoperations.KeyValueMapOperationsStepDefinition.digest(KeyValueMapOperationsStepDefinition.java:180) ~[keyvaluemap-operations-1.0.0.jar:na]
        at com.apigee.steps.keyvaluemapoperations.KeyValueMapOperationsStepDefinition.handleAdd(KeyValueMapOperationsStepDefinition.java:197) ~[keyvaluemap-operations-1.0.0.jar:na]
        at com.apigee.entities.AbstractConfigurator.handleUpdate(AbstractConfigurator.java:130) [config-entities-1.0.0.jar:na]
        at com.apigee.messaging.runtime.Application.handleUpdate(Application.java:229) [message-processor-1.0.0.jar:na]

2018-02-27 14:14:50,344  Apigee-Main-6 ERROR BOOTSTRAP - RuntimeConfigurationServiceImpl.dispatchToListeners() : RuntimeConfigurationServiceImpl.dispatchToListeners : Error occurred while dispatching the request DeployEvent{organization='myorg', application='CustomerAPI', applicationRevision='1', deploymentSpec=basepath=/;env=test;, deploymentID=null} to com.apigee.application.bootstrap.listeners.MessageProcessorBootstrapListener@5009d06e
com.apigee.keyvaluemap.KeyValueMapApiException: KeyValueMap name  is invalid
        at com.apigee.keyvaluemap.service.legacy.KeyValueMapServiceImpl.validateMapName(KeyValueMapServiceImpl.java:125) ~[keyvaluemap-1.0.0.jar:na]
        at com.apigee.keyvaluemap.service.legacy.KeyValueMapServiceImpl.createOrUpdateKeyValueMap(KeyValueMapServiceImpl.java:185) ~[keyvaluemap-1.0.0.jar:na]
        at com.apigee.steps.keyvaluemapoperations.KeyValueMapOperationsStepDefinition.digest(KeyValueMapOperationsStepDefinition.java:180) ~[keyvaluemap-operations-1.0.0.jar:na]
        at com.apigee.steps.keyvaluemapoperations.KeyValueMapOperationsStepDefinition.handleAdd(KeyValueMapOperationsStepDefinition.java:197) ~[keyvaluemap-operations-1.0.0.jar:na]
        at com.apigee.entities.AbstractConfigurator.handleUpdate(AbstractConfigurator.java:130) ~[config-entities-1.0.0.jar:na]
        at com.apigee.messaging.runtime.Application.handleUpdate(Application.java:229) ~[message-processor-1.0.0.jar:na]

  4. 上述的第二個例外狀況表示「API Proxy: CustomerAPI, 修訂版本: 1」發生部署錯誤。

  5. 檢查堆疊追蹤，您可以注意到執行 KeyValuMapOperations 政策時擲回錯誤。

  6. 深入查看 API Proxy 組合時，您發現有一個 KeyValuMapOperations 政策，其程式碼如下所示：

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Pulling-Keys" mapIdentifier="">
 <DisplayName>Pulling Keys</DisplayName>
 <Properties/>
 <ExclusiveCache>false</ExclusiveCache>

  7. 如上所述，mapIdentifier (代表 KeyValueMap 的名稱) 包含空字串。KeyValueMap 名稱不得為空白字串。這是 Deployment 發生錯誤的原因。

解析度

  1. 修改 KeyValueMapOperations 政策，為 KeyValueMap 提供適當的有效名稱。

  2. 在上述範例中，我們藉由修改 KeyValueMapOperations 將 KeyValueMap 名稱改為「MyKeyValueMap」，以解決這個問題，如下所示：

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Pulling-Keys" mapIdentifier="MyKeyValueMap">
    <DisplayName>Pulling Keys</DisplayName>
    <Properties/>
    <ExclusiveCache>false</ExclusiveCache>

必須收集診斷資訊

如果按照上述指示操作後仍無法解決問題，請收集以下診斷資訊。請與 Apigee Edge 支援團隊聯絡，向他們提供收集到的資訊。

  1. 指令的輸出內容

    curl -v <management-server-host>:<port #>/v1/runtime/organizations/<org-name>/environments/<env-name>/apis/<apiproxy-name>/revisions/deployments -u <user>

  2. 訊息處理器記錄

    /opt/apigee/var/log/edge-message-processor/logs/system.log

  3. 詳細說明這份教戰手冊中有哪些部分經過嘗試，以及提供其他深入分析，協助我們快速解決這個問題。