您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息
问题
通过 Edge 界面或 Management API 部署 API 代理或共享流修订版本失败,并显示配置失败错误。
错误消息
您会在 Edge 界面中收到一条错误消息,如下所示:
The revision is deployed, but traffic cannot flow.
com.apigee.kernel.exceptions.spi.UncheckedException{ code = application.bootstrap.FailedToConfigure, message = Configuration failed, associated contexts = []}
以下是在 Edge 界面中观察到的错误消息示例的屏幕截图:
可能的原因
由于许多不同的原因,API 代理的部署可能会失败,并显示“配置失败”错误。下表列出了导致此错误的几个常见原因:
原因 | 说明 | 问题排查说明适用于 |
JavaCallout 政策中缺少 Java 类 | JavaCallout 政策引用的 JAR 文件中缺少 Java 类。 | Edge Private Cloud 用户 |
条件流的条件中使用的运算数不正确 | 在条件中运算符一侧或两侧使用的运算数/表达式无效。 | |
“消息日志记录”政策中的主机名无效 | MessageLogging 政策中使用的主机名无法解析,或可能包含一些不需要的特殊字符。 | |
KeyValueMap 名称无效 | 在 API 代理的 KeyValueMapOperations 政策中,KeyValueMap 无效或为空。 |
常见诊断步骤
使用以下 API 获取发生部署错误的 API 代理特定修订版本的部署状态:
curl -v <management-server-host>:<port#>/v1/runtime/organizations/<org-name>/environments/<env-name>/apis/<apiproxy-name>/revisions/deployments -u <user>
以下是上述 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" },
您会在部署状态输出的每个消息处理器中看到错误消息“Configuration failed”。
登录其中一个消息处理器,并检查日志
/opt/apigee/var/log/edge-message-processor/logs/system.log
。查看在 API 代理部署期间是否出现任何错误。根据在消息处理器日志中观察到的错误/异常,您需要遵循相应的问题排查步骤和问题解决方法。
下面几部分介绍了一些最常见的会导致部署错误“Configuration failed”(配置失败)的异常,并提供了排查和解决这些错误的步骤。
原因:JavaCallout 政策中缺少 Java 类
诊断
- 在消息处理器日志中,如果您在部署 API 代理 (DeployEvent) 期间看到任何异常 "Failed to instantiate the JavaCallout Class",请继续执行第 2 步。如果不正确,请参阅条件流的条件中使用的运算数不正确。
在 API 代理部署期间,消息处理器会显示以下异常:
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>
上述异常中的错误消息表示无法实例化 JavaCallout 类
com.something.apigee.callout.crypto.main.SecretCallout
。当 JavaCallout 政策中指定的 JAR 文件或其任何依赖的 JAR 文件中没有特定类时,通常会发生此错误。检查包含与软件包
com.something.apigee.callout.crypto.main
相关的所有类的 JAR 文件,并确认缺少特定的com.something.apigee.callout.crypto.main.SecretCallout
类。
分辨率
- 将缺少的类添加到特定 JAR 文件中,然后上传该 JAR 文件。
- 重新部署 API 代理。
- 在上面的示例中,我们通过以下方式解决了这个问题:
- 将缺少的
com.something.apigee.callout.crypto.main.SecretCallout
类添加到 JAR 文件中。 - 上传更新后的 JAR 文件并重新部署 API 代理。
- 将缺少的
原因:条件流中的运算符使用了错误的操作数
诊断
在消息处理器日志中,如果您在部署 API 代理或共享流期间看到
com.apigee.expressions.parser.ParseException
(如下面的示例消息所示),请继续执行第 2 步。如果不是,请转到下一个导致 Message Logging 政策中的主机名无效的原因。错误消息示例
com.apigee.expressions.parser.ParseException: Both the operands for EQUALS expression should be data expressions
下面我们来看一个示例,了解如何诊断此问题。
示例:<Operator> 表达式的操作数应为数据表达式
在部署共享流期间,消息处理器会显示以下异常:
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>
ParseException 中的错误消息“
Both the operands for EQUALS expression should be data expressions
”表示,某个条件涉及等于 (=)、不等于 (!=) 或带有 (=|) 运算符的统计数据。查看涉及错误消息中提及的特定运算符的所有条件流中的条件,看看是否存在以下任何问题:
- 运算符两侧的表达式属于同一类型。例如,如果运算符的左侧有一个字符串变量,则右侧需要再指定一个字符串变量或字符串值。
- 在运算符之间使用有效变量。
- 运算符和每个表达式之间有一个空格。
如果不满足上述任何条件,您就会获得 ParseException -“
Both the operands for EQUALS expression should be data expressions
”。让我们通过一个示例来了解此问题。下面是一个错误情况示例
<Condition> (fault.name = "invalid_access_token") or(fault.name = "ApiKeyNotApproved") </Condition>
在此示例中,您可以发现,“or”运算符和下一个条件之间没有空格。因此,在解析第二个条件时,对于 EQUALS 运算符,将第一个表达式视为 "or(fault.name")。此变量名称无效,因此不会将其视为有效的数据表达式。因此,您收到以下异常:
com.apigee.expressions.parser.ParseException: Both the operands for EQUALS expression should be data expressions
分辨率
- 确保运算符的两侧始终使用正确的数据表达式。
在上面讨论的示例中,解决方法是确保“or”运算符后面有空格,如以下代码段所述:
<Condition> (fault.name = "invalid_access_token") or (fault.name = "ApiKeyNotApproved") </Condition>
MessageLogging 政策中的主机名无效
诊断
在消息处理器日志中,如果您在部署 API 代理或共享流(如下所示)期间看到 “Invalid HostName”消息出现异常,请继续执行第 2 步。如果不是,请转到下一个导致 KeyValueMap Name 无效的原因。
com.apigee.rest.framework.ValidationException: Invalid syslog config: Invalid HostName 'splunkprod.myorg.com/' for Syslog handler
让我们来看看以下两个示例,了解如何排查和解决此问题。
示例 1:主机名包含多余的特殊字符
在 API 代理部署期间,消息处理器会显示以下异常:
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>
上面的异常表明,部署失败是因为 "Invalid HostName '<hostname>' for Syslog process"。这表示 MessageLogging 政策中使用的主机名是无效的主机名。
仔细查看消息处理器日志中的异常可以发现,主机名
'splunkprod.myorg.com/'.
末尾有多余的特殊字符“/”这种不需要的特殊字符导致了部署错误。
分辨率
- 修改 MessageLogging 政策以移除任何不需要的特殊字符,以解决此问题。
- 在上述示例中,特殊字符“/”已从 MessageLogging 政策中移除。这解决了问题。
示例 2:主机名无法解析
消息处理器日志中有几行数据,显示了 API 代理的部署事件已触发,随后在 API 代理部署期间发生的异常情况如下:
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>
上面的异常表明,部署失败是因为 "Invalid HostName '<hostname>' for Syslog process"。
如果您仔细阅读异常情况上方的一行,就会发现消息处理器无法解析 MessageLogging 政策中提供的主机名
'input-prd.cloud.splunk.com'
。如需确认这一点,您可以尝试远程登录到 Message Logging 政策中使用的主机名和端口 #。
检查 API 代理特定修订版本中的 MessageLogging 政策,并验证使用的主机名和端口编号。在上述示例中,API 代理名称: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>
使用特定端口 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
这清楚地证明了主机名无法解析。
分辨率
- 修改 MessageLogging 政策以使用有效的主机名。
如果问题仍然存在,请参阅必须收集诊断信息。
原因:KeyValueMap 名称无效
诊断
在消息处理器日志中,如果您在部署 API 代理或共享流期间看到异常消息 "KeyValueMap name is invalid"(如下所示),请继续执行第 2 步。如果不能,请参阅必须收集诊断信息。
com.apigee.rest.framework.ValidationException: Invalid syslog config: Invalid HostName 'splunkprod.myorg.com/' for Syslog handler
下面我们来看一个示例,了解如何排查和解决此问题。
消息处理器日志示例,显示了导致 API 代理部署期间出错的消息“KeyValueMap name is invalid”
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]
上面的第二个异常表示发生 API 代理:CustomerAPI,修订版:1 部署错误。
检查堆栈轨迹,您会注意到在执行 KeyValuMapOperations 政策时抛出了错误。
查看 API 代理软件包,您发现有一项 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>
如上所示,表示 KeyValueMap 名称的 mapIdentifier 为空字符串。KeyValueMap 名称不能为空字符串。这是导致出现部署错误的原因。
分辨率
- 修改 KeyValueMapOperations 政策,为 KeyValueMap 使用正确的有效名称。
在上面的示例中,我们通过修改 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 支持团队,向他们提供收集到的信息。
命令的输出
curl -v <management-server-host>:<port #>/v1/runtime/organizations/<org-name>/environments/<env-name>/apis/<apiproxy-name>/revisions/deployments -u <user>
消息处理器日志
/opt/apigee/var/log/edge-message-processor/logs/system.log
详细说明本手册中的哪些部分进行了尝试,以及任何其他有助于我们快速解决此问题的数据分析。