Back to Details

run-service-scan-and-view-results

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Run Scan and View Results

运行扫描并查看结果

Overview

概述

Executes a scanner configuration to discover services from an external platform, then retrieves the scan results including all discovered services. This is useful for manually triggering scans or reviewing what was found.
What you'll build: A complete scan execution with visibility into discovered services ready for publication to Exchange.
执行 scanner 配置以发现外部平台中的服务，然后检索扫描结果，包括所有已发现的服务。这适用于手动触发扫描或查看扫描发现的内容。
你将构建的内容： 一个完整的扫描执行流程，并可清晰查看已发现的服务，以便发布到 Exchange。

Prerequisites

前提条件

Before starting, ensure you have:
  1. Existing Scanner Configuration
  • A scanner configuration already set up (see "Set Up a Scanner" skill)
  • Valid connection credentials that haven't expired
  1. Anypoint Platform Access
  • Valid authorization token
  • Permission to execute scans in your organization
开始之前，请确保具备以下条件：
  1. 现有 Scanner 配置
    • 已完成 scanner 配置（请参阅“Set Up a Scanner”skill）
    • 拥有有效且未过期的连接凭据
  2. Anypoint Platform 访问权限
    • 拥有有效的 authorization token
    • 拥有在你的组织中执行扫描的权限

Step 1: Execute the Scanner

第 1 步：执行 Scanner

Trigger the scanner to start discovering services from the configured external platform.
What you'll need:
  • Your organization ID
  • Scanner configuration ID
Action: Start the scan execution.
yaml
api: urn:api:agent-scanner-configuration-service
operationId: executeWorkflowFromConfiguration
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: getOrganizations
      field: $.id
      name: currentOrganization
    description: Your organization's Business Group GUID
  scannerConfigurationId:
    from:
      api: urn:api:agent-scanner-configuration-service
      operation: getScanConfigurations
      field: $.content[*].id
    description: The scanner configuration to execute
outputs: []
What happens next: The scan starts asynchronously. You'll receive a 202 Accepted response. The scan runs in the background, discovering services from the external platform.
Common issues:
  • 409 Conflict: A scan is already running for this configuration. Wait for it to complete.
  • 404 Not Found: Scanner configuration doesn't exist or was deleted
  • 503 Service Unavailable: Scan service is temporarily unavailable
触发 scanner，开始从已配置的外部平台发现服务。
所需信息：
  • 你的组织 ID
  • Scanner 配置 ID
操作： 启动扫描执行。
yaml
api: urn:api:agent-scanner-configuration-service
operationId: executeWorkflowFromConfiguration
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: getOrganizations
      field: $.id
      name: currentOrganization
    description: Your organization's Business Group GUID
  scannerConfigurationId:
    from:
      api: urn:api:agent-scanner-configuration-service
      operation: getScanConfigurations
      field: $.content[*].id
    description: The scanner configuration to execute
outputs: []
接下来会发生什么： 扫描将异步启动。你会收到 202 Accepted 响应。扫描在后台运行，并从外部平台发现服务。
常见问题：
  • 409 Conflict：此配置已有扫描正在运行。请等待其完成。
  • 404 Not Found：Scanner 配置不存在或已被删除
  • 503 Service Unavailable：扫描服务暂时不可用

Step 2: Get Scanner Run History

第 2 步：获取 Scanner 运行历史

Check the status of your scan by retrieving the run history.
What you'll need:
  • Organization ID
  • Scanner ID (same as scanner configuration ID)
Action: Retrieve the list of scan runs to find your execution.
yaml
api: urn:api:agent-scanner-configuration-service
operationId: getScannerRunHistory
inputs:
  organizationId:
    from:
      variable: organizationId
    description: Same organization ID as Step 1
  scannerId:
    from:
      variable: scannerConfigurationId
    description: The scanner configuration ID (used as scanner ID)
  page:
    value: "0"
    description: Page number (0-indexed)
  size:
    value: "20"
    description: Number of results per page
outputs:
  - name: scanRunId
    path: $.content[0].id
    description: The most recent scan run ID
  - name: scanStatus
    path: $.content[0].status
    description: Current status (RUNNING, COMPLETED, FAILED, ABORTED)
  - name: startedAt
    path: $.content[0].startedAt
    description: When the scan started
  - name: endedAt
    path: $.content[0].endedAt
    description: When the scan completed (null if still running)
What happens next: You receive a paginated list of scan runs sorted by most recent. Check the status field to see if your scan is still RUNNING or has COMPLETED.
Common issues:
  • Empty results: No scans have been run yet for this scanner
  • Status shows FAILED: Check the scanner configuration's lastRunStatusDetail for error information
通过检索运行历史记录来检查扫描状态。
所需信息：
  • 组织 ID
  • Scanner ID（与 Scanner 配置 ID 相同）
操作： 检索扫描运行列表，以查找你的执行记录。
yaml
api: urn:api:agent-scanner-configuration-service
operationId: getScannerRunHistory
inputs:
  organizationId:
    from:
      variable: organizationId
    description: Same organization ID as Step 1
  scannerId:
    from:
      variable: scannerConfigurationId
    description: The scanner configuration ID (used as scanner ID)
  page:
    value: "0"
    description: Page number (0-indexed)
  size:
    value: "20"
    description: Number of results per page
outputs:
  - name: scanRunId
    path: $.content[0].id
    description: The most recent scan run ID
  - name: scanStatus
    path: $.content[0].status
    description: Current status (RUNNING, COMPLETED, FAILED, ABORTED)
  - name: startedAt
    path: $.content[0].startedAt
    description: When the scan started
  - name: endedAt
    path: $.content[0].endedAt
    description: When the scan completed (null if still running)
接下来会发生什么： 你会收到按最新优先排序的分页扫描运行列表。检查 status 字段，以确定扫描仍在 RUNNING，还是已经 COMPLETED。
常见问题：
  • 结果为空：此 Scanner 尚未运行过任何扫描
  • 状态显示 FAILED：查看 Scanner 配置中的 lastRunStatusDetail，了解错误信息

Step 3: View Discovered Services

第 3 步：查看已发现的服务

Once the scan completes, retrieve the list of discovered services (staging assets).
What you'll need:
  • Scanner ID
  • Scan run ID from Step 2
Action: Get the staging assets discovered during the scan.
yaml
api: urn:api:agent-scanner-configuration-service
operationId: getStagingAssetsByScanRunId
inputs:
  scannerId:
    from:
      variable: scannerId
    description: The scanner ID
  scanRunId:
    from:
      variable: scanRunId
    description: The scan run ID from Step 2
  page:
    value: "0"
    description: Page number (0-indexed)
  size:
    value: "0"
    description: Use 0 to get all results without pagination
outputs:
  - name: assetId
    path: $.content[*].assetId
    description: The asset ID in Exchange (if published)
  - name: assetName
    path: $.content[*].name
    description: Name of the discovered service
  - name: stagingStatus
    path: $.content[*].stagingStatus
    description: Status (NEW, EXISTING, PUBLISHED, FAILED)
  - name: operationPerformed
    path: $.content[*].operationPerformed
    description: What action was taken (CREATE, UPDATE, DELETE, SKIP)
What happens next: You receive a list of all services discovered during the scan, including their names, descriptions, and publication status.
扫描完成后，检索已发现服务（staging assets）的列表。
所需信息：
  • Scanner ID
  • 第 2 步中的扫描运行 ID
操作： 获取扫描期间发现的 staging assets。
yaml
api: urn:api:agent-scanner-configuration-service
operationId: getStagingAssetsByScanRunId
inputs:
  scannerId:
    from:
      variable: scannerId
    description: The scanner ID
  scanRunId:
    from:
      variable: scanRunId
    description: The scan run ID from Step 2
  page:
    value: "0"
    description: Page number (0-indexed)
  size:
    value: "0"
    description: Use 0 to get all results without pagination
outputs:
  - name: assetId
    path: $.content[*].assetId
    description: The asset ID in Exchange (if published)
  - name: assetName
    path: $.content[*].name
    description: Name of the discovered service
  - name: stagingStatus
    path: $.content[*].stagingStatus
    description: Status (NEW, EXISTING, PUBLISHED, FAILED)
  - name: operationPerformed
    path: $.content[*].operationPerformed
    description: What action was taken (CREATE, UPDATE, DELETE, SKIP)
接下来会发生什么： 你会收到扫描期间发现的所有服务列表，其中包括服务名称、描述和发布状态。

Completion Checklist

完成检查清单

After completing all steps, verify:
  • Scan was triggered (202 Accepted)
  • Scan run appears in history with status COMPLETED
  • Staging assets list shows discovered services
  • Review service details for accuracy before publication
完成所有步骤后，请验证：
  • 已触发扫描（202 Accepted）
  • 运行历史记录中显示该扫描，状态为 COMPLETED
  • Staging assets 列表显示已发现的服务
  • 发布前检查服务详情，确保信息准确

What You've Built

你已经构建的内容

Your scan execution has produced:
Scan Run Record
  • Timestamped execution record
  • Status tracking (RUNNING -> COMPLETED)
  • Summary of discovered services
Discovered Services
  • List of services from the external platform
  • Service metadata (name, description, capabilities)
  • Staging status for Exchange publication
你的扫描执行已生成：
扫描运行记录
  • 带时间戳的执行记录
  • 状态跟踪（RUNNING -> COMPLETED）
  • 已发现服务的摘要
已发现的服务
  • 来自外部平台的服务列表
  • 服务元数据（名称、描述、能力）
  • 用于 Exchange 发布的 staging 状态

Next Steps

后续步骤

Now that you've seen the discovered services:
  1. Review service details
  • Check the service payload for each discovered service
  1. Monitor publication
  • Agents with stagingStatus PUBLISHED are live in Exchange
  1. Handle failures
  • Review services with stagingStatus FAILED for issues
  1. Schedule regular scans
  • Configure automatic scheduled scans for continuous discovery
查看已发现的服务后：
  1. 检查服务详情
    • 检查每个已发现服务的 service payload
  2. 监控发布情况
    • stagingStatus 为 PUBLISHED 的 Agent 已在 Exchange 中上线
  3. 处理失败情况
    • 检查 stagingStatus 为 FAILED 的服务并排查问题
  4. 定期安排扫描
    • 配置自动定时扫描，以持续发现服务

Tips and Best Practices

提示与最佳实践

Monitoring Scans

监控扫描

  • Poll status: For long-running scans, poll getScannerRunHistory every 30-60 seconds
  • Check summary: The scan run summary field contains counts of discovered/updated/failed services
  • 轮询状态：对于长时间运行的扫描，每 30–60 秒轮询一次 getScannerRunHistory
  • 检查摘要：扫描运行摘要字段包含已发现、已更新和失败服务的数量

Understanding Staging Status

了解 Staging 状态

  • NEW: Service discovered for the first time
  • EXISTING: Service already known, checked for updates
  • PUBLISHED: Successfully published to Exchange
  • FAILED: Publication failed (check summary for details)
  • PENDING_UPDATE: Service has changes pending publication
  • NEW：首次发现的服务
  • EXISTING：已知服务，已检查是否有更新
  • PUBLISHED：已成功发布到 Exchange
  • FAILED：发布失败（查看摘要了解详情）
  • PENDING_UPDATE：服务有变更等待发布

Troubleshooting

故障排查

Scan Stuck in RUNNING State

扫描一直处于 RUNNING 状态

Symptoms: Scan status remains RUNNING for an extended period
Possible causes:
  • Large number of services to discover
  • Network issues with external platform
  • Processing delays
Solutions:
  • Wait longer for large environments (can take 10-30 minutes)
  • Check external platform connectivity
  • Use abort endpoint if scan appears stuck
症状： 扫描状态长时间保持为 RUNNING
可能原因：
  • 待发现的服务数量较多
  • 与外部平台之间存在网络问题
  • 处理延迟
解决方案：
  • 对于大型环境，请等待更长时间（可能需要 10–30 分钟）
  • 检查与外部平台的连接
  • 如果扫描看起来已经卡住，请使用 abort endpoint

No Services Discovered

未发现任何服务

Symptoms: Scan completes but staging assets list is empty
Possible causes:
  • No services exist in the external platform
  • Connection credentials lack read permissions
  • Platform-specific filters exclude all services
Solutions:
  • Verify services exist in the source platform
  • Check connection credentials have appropriate permissions
  • Review scanner configuration parameters
症状： 扫描已完成，但 staging assets 列表为空
可能原因：
  • 外部平台中不存在任何服务
  • 连接凭据缺少读取权限
  • 特定于平台的筛选条件排除了所有服务
解决方案：
  • 验证源平台中确实存在服务
  • 检查连接凭据是否拥有适当的权限
  • 检查 Scanner 配置参数

Scan Fails Immediately

扫描立即失败

Symptoms: Scan status shows FAILED shortly after starting
Possible causes:
  • Invalid or expired credentials
  • External platform API unavailable
  • Configuration error
Solutions:
  • Test the connection using the connectivity test endpoint
  • Verify external platform is accessible
  • Check lastRunStatusDetail on the scanner configuration
症状： 扫描启动后不久，状态即显示为 FAILED
可能原因：
  • 凭据无效或已过期
  • 外部平台 API 不可用
  • 配置错误
解决方案：
  • 使用 connectivity test endpoint 测试连接
  • 验证外部平台是否可访问
  • 检查 Scanner 配置中的 lastRunStatusDetail

Related Jobs

相关任务

  • setup-service-scanner: Create a new scanner configuration
  • setup-service-scanner：创建新的 Scanner 配置