使用FMC API資源管理器排除對象建立故障

下載選項

  • PDF     (1.3 MB)
    在多種裝置上使用 Adobe Reader 檢視
  • ePub     (1.1 MB)
    在 iPhone、iPad、Android、Sony Reader 或 Windows Phone 上的各種應用程式中檢視
  • Mobi (Kindle)     (1.0 MB)
    在 Kindle 裝置或多部裝置的 Kindle 應用程式上檢視
已更新: 2025 年 6 月 26 日
文件 ID:223159

無偏見用語

本產品的文件集力求使用無偏見用語。針對本文件集的目的，無偏見係定義為未根據年齡、身心障礙、性別、種族身分、民族身分、性別傾向、社會經濟地位及交織性表示歧視的用語。由於本產品軟體使用者介面中硬式編碼的語言、根據 RFP 文件使用的語言，或引用第三方產品的語言，因此本文件中可能會出現例外狀況。深入瞭解思科如何使用包容性用語。

關於此翻譯

思科已使用電腦和人工技術翻譯本文件，讓全世界的使用者能夠以自己的語言理解支援內容。請注意，即使是最佳機器翻譯，也不如專業譯者翻譯的內容準確。Cisco Systems, Inc. 對這些翻譯的準確度概不負責，並建議一律查看原始英文文件（提供連結）。

    簡介

    本文檔介紹API管理員如何使用API資源管理器將網路、埠和URL對象批次推送到FMC。

    必要條件

    需求

    思科建議您瞭解以下主題：

    採用元件

    • 支援REST API（7.4版或更高版本）並啟用REST API的Firepower管理中心
    • 整合在FMC中的API Explorer

    本文中的資訊是根據特定實驗室環境內的裝置所建立。文中使用到的所有裝置皆從已清除（預設）的組態來啟動。如果您的網路運作中，請確保您瞭解任何指令可能造成的影響。

    限制

    • FMC不接受對象名稱大於64個字元。
    • 對象名稱在對象名稱開頭不能有空格，在結尾不能有分號。
    • 負載在單個批次推送中不能包含超過1,000個條目。
    • 單個批次推送中的負載大小不能超過2MB。

    背景資訊

    REST API日益流行，因為網路管理員可以使用輕量級的可程式設計方法配置和管理其網路。FMC支援使用任何REST客戶端以及使用內建API資源管理器的配置和管理。

    本文提供解決通過Firepower管理中心(FMC)API資源管理器建立對象時遇到的問題的故障排除步驟。無論您是使用網路對象、主機對象還是FTD配置，這些步驟都有助於確定常見問題並實施有效的解決方案。

    在所有網路對象型別中保持通用的JSON屬性包括：

    1. Value — 此屬性提供Network value with CIDR等資訊，例如，主機對象可以將x.x.x.x作為IP，網路可以將x.x.x/<prefix>作為CIDR的子網。
    2. Type — 此屬性提供有關用於配置對象(主機、網路、服務、範圍和FQDN)的對象類型的資訊。
    3. Name — 此屬性提供有關對象名稱的資訊
    4. Description — 此屬性可用於提供有關對象的一些有用資訊或註釋
    5. Overrideable - 對象覆蓋允許您為對象定義替代值，系統將此值用於指定的裝置。這是可用於建立對象的可選屬性。

    組態

    在FMC上啟用API

    在Cisco FMC上啟用REST API。有關「如何啟用REST API」和「最佳實踐」的詳細資訊，請參閱在Cisco FMC上啟用REST API

    導航到System > Configuration > REST API Preferences > Select "Enable REST API"

    API Explorer駐留在管理中心上，可通過管理中心訪問：

    https://<management_center_IP_or_name>:<https_port>/api/api-explorer 

    note-icon

    附註：如果使用標準HTTPS埠TCP 443，則從URL中安全刪除「：<https_port」。

    遇到常見錯誤

    我們正在討論使用API資源管理器和POST方法建立對象時遇到的最常見錯誤。之後將討論每個網路對象的正確格式。

    1.無效訪問令牌：

    JSON response for invalid access token無效訪問令牌的JSON響應

    note-icon

    附註：當會話過期時，會遇到此錯誤。重新載入FMC API資源管理器並重新進行身份驗證。

    2.使用的格式無效：

    {
  "name": "API_1",
  "type": "Host",
  "value": "10.5.3.20"
  "description": "Test Description"
}

    Sample JSON request to create object建立對象的JSON請求示例

    Failed JSON response due to missing comma由於缺少逗號，JSON響應失敗

    note-icon

    附註：JSON格式中缺少逗號時，大多數情況下都會遇到此錯誤。在本例中("value":「10.5.3.20」)沒有導致此失敗的逗號。只有JSON格式的最後一個Attribute不能有逗號，否則它可能會導致失敗。

    3.建立對象時使用的輸入無效：

    {
  "name": "net2",
  "value": "1.1.0.0/24",
  "overridable": false,
  "description": "Network obj 2",
  "type": "Network"
}

    Failed JSON response for invalid type無效的JSON響應失敗

    note-icon

    附註：在此示例中，試圖在Network Object的具有JSON負載的Hosts類別中建立對象，結果出現了錯誤：「Input type mismatch」。 使用為每個網路對象(主機、網路、FQDN、服務和範圍)指定的正確格式。

    4.使用GET方法響應負載建立對象

    {
      "links": {
        "self": "https://10.197.207.3/api/fmc_config/v1/domain/e276abec-e0f2-11e3-8169-6d9ed49b625f/object/hosts/00000000-0000-0ed3-0000-034359741703",
        "parent": "https://10.197.207.3/api/fmc_config/v1/domain/e276abec-e0f2-11e3-8169-6d9ed49b625f/object/networkaddresses"
      },
      "type": "Host",
      "name": "API_2",
      "id": "00000000-0000-0ed3-0000-034359741703"
}

    GET request to fetch host objects獲取主機對象的GET請求

    Failed JSON response due to missing value attribute由於缺少值屬性，JSON響應失敗

    Failed JSON response where object is created in incorrect format以不正確的格式建立對象的JSON響應失敗

    note-icon

    附註：在本示例中，使用GET方法獲取的JSON負載中缺少Value屬性，並且expanded引數設定為預設值。對於對象建立，JSON負載中可能存在一些必需的屬性，這些屬性是大多數網路對象(主機、網路、範圍、服務和FQDN)的類型、名稱和值。 使用GET方法的JSON負載建立對象時，請僅使用在items屬性內的對象相關資訊，並刪除id屬性，以便不出現UUID衝突。

    建立主機對象

    單個主機對象

    導覽至Object > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST，然後單擊Try it Out。

    用於推送單個主機對象的JSON格式：

    {
  "name": "Obj_API_100.1.1.1",
  "type": "Host",
  "value": "100.1.1.1",
  "description": "Host Object Pushed via API"
}

    POST operation to create host object建立主機對象的POST操作

    note-icon

    附註：對單個主機對象使用POST操作時，使用預設的「批次引數」。

    批次主機對象

    導覽至Object > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST，然後單擊Try it Out。

    用於推送批次主機對象的JSON格式：

    [
	{
	"name": "Obj_API_172.16.0.1",
	"type": "Host",
	"value": "172.16.0.1",
	"description": "Bulk API Operation"
	},
	{
	"name": "Obj_API_172.16.0.2",
	"type": "Host",
	"value": "172.16.0.2",
	"description": "Bulk API Operation"
	}
]

    Sample JSON request to create bulk objects建立批次對象的JSON請求示例

    Sample JSON Response after creating bulk objects建立批次對象之後的JSON響應示例

    note-icon

    附註：建立批次主機對象時，請選擇批次引數作為真。在單個Bulk Push中，可以使用POST方法建立最多1000個條目。

    建立網路對象

    單個網路對象

    導覽至Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST，然後單擊Try it Out。

    用於推送單個網路對象的JSON格式：

    {
  "name": "Obj_API_network",
  "value": "7.0.0.0/24",
  "overridable": false,
  "description": "Single Network object created",
  "type": "Network"
}

    Sample JSON request to create single network object建立單個網路對象的JSON請求示例

    批次網路對象

    導覽至Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST，然後單擊Try it Out。

    用於推送批次網路對象的JSON格式：

    [
  {
    "name": "Obj_API_net1",
    "value": "1.0.0.0/24",
    "overridable": false,
    "description": "Bulk Operation",
    "type": "Network"
  },
  {
    "name": "Obj_API_net2",
    "value": "1.1.0.0/24",
    "overridable": false,
    "description": "Bulk Operation",
    "type": "Network"
  }
]

    Sample JSON request to create bulk network objects建立批次網路對象的JSON請求示例

    note-icon

    附註：建立批次網路對象時，選擇批次引數作為True。在單個Bulk Push中，可以使用POST方法建立最多1000個條目。

    建立網路範圍對象

    單個網路範圍對象

    導覽至Object > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST，然後單擊Try it Out。

    用於推送單個範圍對象的JSON格式：

    {
  "name": "Obj_API_TestRange",
  "value": "10.2.30.40-10.2.30.50",
  "type": "Range",
  "description": "Create Single Range Object"
}

    批次網路範圍對象

    導覽至Object > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST，然後單擊Try it Out。

    用於推送批次範圍對象的JSON格式：

    [
  {
    "name": "Obj_API_TestRange1",
    "value": "10.4.30.40-10.4.30.50",
    "type": "Range",
    "description": "Bulk Operation"
  },
  {
    "name": "Obj_API_TestRange2",
    "value": "10.5.30.40-10.5.30.50",
    "type": "Range",
    "description": "Bulk Operation"
  }
]
    note-icon

    附註：建立主體範圍對象時，選擇Bulk Parameter作為True。在單個Bulk Push中，可以使用POST方法建立最多1000個條目。

    建立FQDN對象

    單個FQDN對象

    導覽至Object > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST，然後單擊Try it Out。

    用於推送單個網路對象的JSON格式：

    {
  "name": "TestFQDN",
  "type": "FQDN",
  "value": "cloud.cisco.com",
  "dnsResolution": "IPV4_ONLY",
  "description": "Create Single FQDN Object"
}

    批次FQDN對象

    導覽至Object > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST，然後單擊Try it Out。

    用於推送批次網路對象的JSON格式：

    [
  {
    "name": "Obj_API_FQDN_1",
    "type": "FQDN",
    "value": "downloads.cisco.com",
    "dnsResolution": "IPV4_ONLY",
    "description": "Bulk Operation"
  },
  {
    "name": "Obj_API_FQDN_2",
    "type": "FQDN",
    "value": "support.cisco.com",
    "dnsResolution": "IPV4_ONLY",
    "description": "Bulk Operation"
  }
]
    note-icon

    注意:建立批次FQDN對象時，選擇批次引數為True。在單個Bulk Push中，可以使用POST方法建立最多1000個條目。

    建立服務對象

    單個服務對象

    導覽至Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolportobjects > POST，然後單擊Try it Out。

    用於推送單個服務對象的JSON格式：

    {
  "name": "Obj_API_Telnet_Port",
  "protocol": "TCP",
  "port": 23,
  "type": "ProtocolPortObject"
}

    用於推送具有範圍的單個服務對象的JSON格式：

    {
  "name": "Obj_API_obj1",
  "protocol": "UDP",
  "port": "1025-65535",
  "type": "ProtocolPortObject"
}
    note-icon

    注意：當您以JSON格式定義埠範圍時，請使用雙引號例如「port」：「1111-1115」否則可能會遇到錯誤："說明":"無法處理的實體 — 意外字元('-'（代碼45）):需要用逗號分隔行中的對象條目：4，列：17"

    批次服務對象

    導覽至Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolportobjects > POST，然後單擊Try it Out。

    用於推送批次服務對象的JSON格式：

    [
  {
    "name": "Obj_API_UDP_Port",
    "protocol": "UDP",
    "port": 123,
    "type": "ProtocolPortObject"
  },
  {
    "name": "Obj_API_TCP_Range",
    "protocol": "TCP",
    "port": "1025-65535",
    "type": "ProtocolPortObject"
  }
]

    note-icon

    注意:建立批次服務對象時，請選擇批次引數為True。在單個Bulk Push中，可以使用POST方法建立最多1000個條目。

    疑難排解

    • 請參閱文檔瞭解HTTP狀態代碼（REST API基礎知識）
    • 使用者憑據不能同時用於REST API和GUI介面，如果同時用於這兩種介面，則使用者將在無警告的情況下註銷。
    • 所有REST請求都記錄到FMC上的這兩個日誌檔案中。搜尋您的URL(例如.../object/hosts)，以及正確的操作(如果您在GET操作中查詢錯誤，請確保您的日誌啟動了GET ...對象/主機)
    tail -f /var/opt/CSCOpx/MDC/tomcat/logs/stdout.logs  
tail -f /var/opt/CSCOpx/MDC/log/operation/usmsharedsvcs.log

    修訂記錄

    修訂 發佈日期 意見
    1.0
    26-Jun-2025
    初始版本
    TAC Authored

    由思科工程師貢獻

    • 阿坎庫·夏爾馬
      技術諮詢工程師

    這份文件是否有所幫助？

    Feedback意見

    讓思科協助您

    本文件適用於這些產品