FMC API 탐색기를 사용하여 개체 생성 문제 해결

다운로드 옵션

  • PDF     (1.2 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는 전 세계 사용자에게 다양한 언어로 지원 콘텐츠를 제공하기 위해 기계 번역 기술과 수작업 번역을 병행하여 이 문서를 번역했습니다. 아무리 품질이 높은 기계 번역이라도 전문 번역가의 번역 결과물만큼 정확하지는 않습니다. Cisco Systems, Inc.는 이 같은 번역에 대해 어떠한 책임도 지지 않으며 항상 원본 영문 문서(링크 제공됨)를 참조할 것을 권장합니다.

    소개

    이 문서에서는 API 관리자가 API Explorer를 사용하여 네트워크, 포트 및 URL 개체를 대량으로 FMC에 푸시하는 방법을 설명합니다.

    사전 요구 사항

    요구 사항

    다음 주제에 대한 지식을 보유하고 있으면 유용합니다.

    사용되는 구성 요소

    • REST API가 활성화된 상태에서 REST API(버전 7.4 이상)를 지원하는 firepower 관리 센터
    • FMC에 통합된 API Explorer

    이 문서의 정보는 특정 랩 환경의 디바이스를 토대로 작성되었습니다. 이 문서에 사용된 모든 디바이스는 초기화된(기본) 컨피그레이션으로 시작되었습니다. 현재 네트워크가 작동 중인 경우 모든 명령의 잠재적인 영향을 미리 숙지하시기 바랍니다.

    제한 사항

    • FMC는 개체의 이름을 64자보다 크게 허용하지 않습니다.
    • 개체 이름은 개체 이름의 시작 부분에 공백을 가질 수 없으며 끝 부분에는 세미콜론을 가질 수 없습니다.
    • 페이로드는 단일 대량 푸시에 1,000개 이상의 항목을 포함할 수 없습니다.
    • 단일 대량 푸시에서 페이로드 크기는 2MB를 초과할 수 없습니다.

    배경 정보

    REST API는 네트워크 관리자가 네트워크를 구성 및 관리하는 데 사용할 수 있는 프로그래밍 가능한 경량 접근 방식 때문에 점점 더 널리 사용되고 있습니다. FMC는 모든 REST 클라이언트와 내장 API 탐색기를 사용하여 컨피그레이션 및 관리를 지원합니다.

    이 문서에서는 FMC(Firepower 관리 센터) API 탐색기를 통해 개체를 만들 때 발생하는 문제를 해결하기 위한 문제 해결 단계를 제공합니다. 네트워크 객체, 호스트 객체 또는 FTD 컨피그레이션 중 무엇을 사용하든 이 단계는 일반적인 문제를 파악하고 효과적인 솔루션을 구현하는 데 도움이 됩니다.

    모든 네트워크 객체 유형에서 공통적으로 유지되는 JSON 특성은 다음과 같습니다.

    1. Value - 이 특성은 CIDR이 포함된 네트워크 값과 같은 정보를 제공합니다. 예를 들어, 호스트 개체는 IP로 x.x.x.x를 가질 수 있고 네트워크는 CIDR이 포함된 서브넷으로 x.x.x/<prefix>를 가질 수 있습니다.
    2. Type - 이 특성은 개체(호스트, 네트워크, 서비스, 범위 및 FQDN)를 구성하는 데 사용되는 개체 유형에 대한 정보를 제공합니다.
    3. 이름 - 이 속성은 객체의 이름에 대한 정보를 제공합니다
    4. 설명 - 이 특성은 개체에 대한 몇 가지 유용한 정보나 설명을 제공하는 데 사용할 수 있습니다
    5. 재정의 가능 - 객체 재정의를 통해 사용자가 지정하는 장치에 대해 시스템에서 사용하는 객체에 대한 대체 값을 정의할 수 있습니다. 객체 생성에 사용할 수 있는 선택적 속성입니다.

    설정

    FMC에서 API 활성화

    Cisco FMC에서 REST API를 활성화합니다. "REST API를 활성화하는 방법" 및 "모범 사례"에 대한 자세한 내용은 Cisco FMC에서 REST API 활성화를 참조하십시오

    System(시스템) > Configuration(컨피그레이션) > REST API Preferences(REST API 환경 설정) > Select "Enable REST API(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 형식의 마지막 특성에만는 오류를 일으킬 수 있는 쉼표가 없어야 합니다.

    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 카테고리에서 object를 만들려고 시도했지만 "입력 유형 불일치"라는 오류가 발생했습니다. 각 네트워크 객체(호스트, 네트워크, 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호스트 개체 가져오기 요청 가져오기

    Failed JSON response due to missing value attribute값 특성이 없어 JSON 응답이 실패했습니다.

    Failed JSON response where object is created in incorrect format개체가 잘못된 형식으로 만들어진 JSON 응답 실패

    note-icon

    참고: 이 예에서 Value 특성은 GET 메서드를 사용하여 가져온 JSON 페이로드에 없으며 확장 매개 변수가 기본값으로 설정됩니다. 대부분의 네트워크 객체(호스트, 네트워크, 범위, 서비스 및 FQDN)에 대한 유형, 이름 및 값의 객체 생성을 위해 JSON 페이로드에 포함될 수 있는 필수 특성이 있습니다. GET 메서드의 JSON 페이로드를 사용하여 개체를 만들 때 항목 특성 내에 있는 개체 관련 정보만 사용하고 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 작업을 사용하는 동안 기본 "Bulk Parameter"를 사용합니다.

    벌크 호스트 개체

    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 Parameter를 True로 선택합니다. 단일 대량 밀어넣기에서 POST 방법을 사용하여 최대 1000개의 항목을 생성할 수 있습니다.

    네트워크 개체 만들기

    단일 네트워크 개체

    Object(개체) > /api/fmc_config/v1/domain/{domainUUID}/object/networks(도메인/UUID}/개체/네트워크) > 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(도메인/UUID}/개체/네트워크) > 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

    참고: 벌크 네트워크 객체를 생성할 때 Bulk Parameter를 True로 선택합니다. 단일 대량 밀어넣기에서 POST 방법을 사용하여 최대 1000개의 항목을 생성할 수 있습니다.

    네트워크 범위 개체 만들기

    단일 네트워크 범위 개체

    Object(개체) > /api/fmc_config/v1/domain/{domainUUID}/object/ranges(도메인/UUID}/개체/범위) > 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(도메인/UUID}/개체/범위) > 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로 선택합니다. 단일 대량 밀어넣기에서 POST 방법을 사용하여 최대 1000개의 항목을 생성할 수 있습니다.

    FQDN 개체 만들기

    단일 FQDN 개체

    Object(개체) > /api/fmc_config/v1/domain/{domainUUID}/object/fqdn > 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/fqdn > 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 객체를 생성할 때 Bulk Parameter를 True로 선택합니다. 단일 대량 밀어넣기에서 POST 방법을 사용하여 최대 1000개의 항목을 생성할 수 있습니다.

    서비스 개체 만들기

    단일 서비스 개체

    Object(개체) > /api/fmc_config/v1/domain/{domainUUID}/object/protocolportobjects(도메인/UUID) > 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)): 쉼표로 구분해야 하는 Object 항목이 다음 줄에 있습니다. 4, 열: 17"

    대량 서비스 개체

    Object(개체) > /api/fmc_config/v1/domain/{domainUUID}/object/protocolportobjects(도메인/UUID) > 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

    참고: 대량 서비스 객체를 생성할 때 Bulk Parameter를 True로 선택합니다. 단일 대량 밀어넣기에서 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

    Cisco 엔지니어가 작성

    • 아칸슈 샤르마
      기술 컨설팅 엔지니어

    이 문서가 도움이 되셨습니까?

    Feedback피드백

    지원 문의

    이 문서가 적용되는 제품