Utilización de la CLI del kit de herramientas para explorar los catálogos y espacios

Editar en línea

Cómo utilizar IBM® API Connect CLI del kit de herramientas para ejecutar exploraciones de validación de gobierno en los catálogos y espacios.

Acerca de

API gobernanza es un servicio API Connect que se puede utilizar para validar y aplicar políticas de gobernanza organizativa y mejores prácticas a su proceso de desarrollo de API. La información siguiente proporciona detalles de los mandatos toolkit CLI para ejecutar y gestionar exploraciones de validación en los catálogos y espacios. Para obtener más información sobre el escaneo de validación, consulta la sección «Escaneo de catálogos y espacios ».

Las secciones siguientes detallan cómo ejecutar mandatos de exploración de validación utilizando la CLI del kit de herramientas.

PRECAUCIÓN: El análisis de catálogos o espacios que contengan más de cien documentos API o de productos, así como el uso de numerosos conjuntos de reglas para dicho análisis, puede tardar horas en completarse y podría agotarse el tiempo de espera antes de que finalice, dependiendo de la carga de trabajo del servidor. Solo se puede escanear un documento a la vez, y cuantos más conjuntos de reglas se apliquen, más tiempo tardará cada escaneo individual. En este escenario, considere la posibilidad de seleccionar sólo unos pocos conjuntos de reglas para cada exploración.

Inicio de sesión en la CLI del kit de herramientas

Inicie sesión en el kit de herramientas como propietario o administrador de la organización de proveedores.
Por ejemplo:
```
apic login --server platform-api-host-name --sso
```
Donde <platform-api-host-name> es la parte del nombre de host URL del servidor que aloja el API Manager (el "servidor de gestión"). Para determinar el nombre de host, abra API Manager en un navegador y copie el nombre de host de URL en la barra de direcciones (empezando después de " https:// " y terminando antes de "/manager") como se muestra en el siguiente ejemplo:
```
https://platform-api.us-east-1.d-r01.apic.cloud.ibm.com/manager
```
Cuando el kit de herramientas solicite el contexto, especifique provider y pulse Intro:
```
Context? provider
```
Para obtener más información sobre el kit de herramientas CLI, consulte Configuración del API Connect kit de herramientas.

Ejecución de mandatos compliance:scan

Los mandatos siguientes detallan cómo ejecutar una exploración de conformidad en un catálogo o espacio.

Cree un JSON COMPLIANCE_REQUEST_FILE que especifique la ubicación del catálogo o espacio y los conjuntos de reglas que se van a utilizar durante una exploración de validación.
Por ejemplo:
```
{
  "collectionUrl": "https://server/api/catalogs/org/catalog",
  "config": {
    "rulesets": [
      {
        "rulesetName": "spectral-oas",
        "disabled": ["info-contact"]
      },
      {
        "rulesetName": "spectral-owasp",
        "disabled": []
      }
    ]
  }
}
```
Donde:
- collectionUrl es la URL del catálogo o espacio que contiene los documentos de la API sobre los que desea ejecutar un análisis de validación, donde server es la URL del servidor, org es el nombre o ID de la organización proveedora y catalog es el nombre o ID del catálogo o espacio. Por ejemplo: https://localhost:3003/api/catalogs/alpha/sandbox.
- rulesets contiene una lista de los conjuntos de reglas que se aplicarán a las API durante la exploración de validación.
  Para cada conjunto de reglas de la lista, puede añadir opcionalmente la propiedad disabled con una lista delimitada por comas de reglas a ignorar durante la validación.
Ejecute una exploración de validación utilizando el mandato compliance:scan .
```
apic --mode governance compliance:scan --scope org --org <target_org> --server <platform_api_host_name> COMPLIANCE_REQUEST_FILE
```
Donde:
- scope es el ámbito de la exploración y debe establecerse en org para una exploración de validación de catálogo o espacio.
- <target_org> es el nombre de la organización de proveedores que contiene el catálogo o espacio que desea volver a explorar.
- <platform_api_host_name> es la parte del nombre de host URL del servidor que aloja el Gestor de API (el "servidor de gestión").
  
  Consejo: Para determinar el nombre de host, puede abrir el Gestor de API en un navegador y copiar el nombre de host de la URL en la barra de direcciones (empezando después de https:// y terminando antes de /manager ).
- COMPLIANCE_REQUEST_FILE es la ruta y el nombre de archivo del archivo JSON que contiene los detalles de configuración para el análisis de validación. Por ejemplo, ./documents/validate-apis.json.
Este comando ejecuta un escaneo en sus APIs.
Para ejecutar un escaneado en sus productos, debe añadir al comando el parámetro opcional ' --scan_type ' con un valor de ' product '. Por ejemplo:
```
apic --mode governance compliance:scan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-products.json --scan_type product
```
puede utilizar el valor api para escanear sólo APIs, o product para escanear sólo productos. Si se omite, sólo se escanean las API.
Los resultados del escaneo se imprimen en la pantalla.
El siguiente parámetro opcional le permite refinar los resultados de este comando.
- --scantitle scan_title es una bandera opcional que cambia el título de la exploración recuperada al valor que usted proporcione.
Por ejemplo:
```
apic --mode governance compliance:scan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-apis.json --scantitle scan1
```
Vuelva a ejecutar una exploración de validación existente utilizando el mandato compliance:rescan .
Una reejecución de exploración crea un nuevo informe para esa exploración, pero utiliza la misma configuración de catálogo o espacio y conjuntos de reglas que se utilizó en la exploración anterior.
```
apic --mode governance compliance:rescan --scope org --org <target_org> --server <platform_api_host_name> --scan <scan_name_or_scan_id>
```
Donde:
- scope es el ámbito de la exploración y debe establecerse en org para una exploración de validación de catálogo o espacio.
- <target_org> es el nombre de la organización de proveedores que contiene el catálogo o espacio que desea volver a explorar.
- <platform_api_host_name> es la parte del nombre de host URL del servidor que aloja el Gestor de API (el "servidor de gestión").
  
  Consejo: Para determinar el nombre de host, puede abrir el Gestor de API en un navegador y copiar el nombre de host de la URL en la barra de direcciones (empezando después de https:// y terminando antes de /manager ).
- scan_name_or_scan_id es el nombre o el ID de la exploración existente que desea volver a ejecutar.
El siguiente parámetro opcional le permite refinar los resultados de este comando.
- --scantitle scan_title es un indicador opcional que cambia el título de la reexploración por el valor que proporciones.
Por ejemplo:
```
apic --mode governance compliance:rescan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-apis.json --scantitle scan2
```

Ejecución de mandatos scans

Los mandatos siguientes detallan cómo gestionar y actualizar las exploraciones de validación.

Liste todas las exploraciones de validación que existen para una organización de proveedores específica utilizando el mandato scans:list .

La devolución incluye información sobre todas las exploraciones de validación y alguna información sobre sus informes de exploración, pero si desea información más detallada sobre los informes, utilice el mandato scan-reports:list .

apic --mode governance scans:list --scope org --org <target_org> --server <platform_api_host_name>

Donde:

scope es el ámbito de la exploración y debe establecerse en org para una exploración de validación de catálogo o espacio.
<target_org> es el nombre de la organización de proveedores para la que desea una lista de exploraciones.
<platform_api_host_name> es la parte del nombre de host URL del servidor que aloja el Gestor de API (el "servidor de gestión").

Consejo: Para determinar el nombre de host, puede abrir el Gestor de API en un navegador y copiar el nombre de host de la URL en la barra de direcciones (empezando después de https:// y terminando antes de /manager ).

El siguiente ejemplo muestra la salida de muestra para una lista que contiene dos exploraciones, una de APIs y otra de productos:

total_results: 2
results:
  - type: 'scan'
    scan_type: '1'
    api_version: '2.0.0'
    id: 'cd765034-d46b-4b1b-9c74-b63911f42773'
    name: 'cd765034-d46b-4b1b-9c74-b63911f42773'
    title: 'API Scan'
    scope: 'org'
    collection:
      id: 'b6deefe8-6cd5-4bcb-b7b4-116891bc6019'
      name: 'cat1'
      type: 'catalog'
      title: 'cat1'
      location: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41/cat1'
    config:
      - id: 'cf16505a-ae70-438b-be10-bcc7678d1eee'
        url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41/rulesets/cf16505a-ae70-438b-be10-bcc7678d1eee'
        name: 'spectral-async'
        title: 'spectral-async'
        version: '1.15.0'
        disabled: []
      - id: '01562ee7-9a50-4dae-b356-9f50ccb6'
        url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41/rulesets/01562ee7-9a50-4dae-b356-9f50ccb6'
        name: 'spectral-oas'
        title: 'spectral-oas'
        version: '1.15.0'
        disabled: []
    documents:
      - id: '29b04204-8cce-47ab-baac-365ab09f'
        name: 'accountservice'
        title: 'AccountService'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/04d6a185-2c6d-41fd-91e6-d7e83a854745/apis/29b04204-8cce-47ab-baac-365ab09f'
      - id: '964f1df0-dd0b-4671-afee-e70af020'
        name: 'awsecommerceservice'
        title: 'AWSECommerceService'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/04d6a185-2c6d-41fd-91e6-d7e83a854745/apis/964f1df0-dd0b-4671-afee-e70af020'
    progress: 100
    reports:
      created_at: '2024-03-27T10:57:09.921Z'
      report_url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/scan-reports/cfd0eac3-cff1-4d66-9057-30426970'
      scan_result:
        hints: '0'
        infos: '20'
        errors: '1396'
        warnings: '24212'
    scan_result: '1396 Errors, 24212 Warnings, 20 Infos, 0 Hints, 6 Rulesets'
    status: 1
    created_at: '2024-03-27T10:55:45.000Z'
    updated_at: '2024-03-27T10:57:12.000Z'
    url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/scans/0e84ce18-45ea-4a28-ab68-4da0c492'
  - type: 'scan'
    scan_type: '2'
    api_version: '2.0.0'
    id: 'ddc5da81-0db0-425c-b74c-5fc8300934e6'
    name: 'ddc5da81-0db0-425c-b74c-5fc8300934e6'
    title: 'Product Scan'
    scope: 'org'
    collection:
      id: 'b6deefe8-6cd5-4bcb-b7b4-116891bc6019'
      name: 'cat2'
      type: 'catalog'
      title: 'cat2'
      location: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/cat2'
    config:
      - id: '8e67e57b-a7f6-4c5e-b341-ab0a960d78fd'
        url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/rulesets/8e67e57b-a7f6-4c5e-b341-ab0a960d78fd'
        name: 'Product Ruleset'
        title: 'Product Ruleset'
        version: '1.0.0'
        disabled: []
    documents:
      - id: 'c6c66be4-bd1e-4fe1-85d5-45fd8a4bd3d0'
        name: 'First Product Document'
        title: 'First Product Document'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/b6deefe8-6cd5-4bcb-b7b4-116891bc6019/products/c6c66be4-bd1e-4fe1-85d5-45fd8a4bd3d0'
      - id: '11266894-524a-410d-babf-ca2488736e40'
        name: 'Second Product Document'
        title: 'Second Product Document'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/b6deefe8-6cd5-4bcb-b7b4-116891bc6019/products/11266894-524a-410d-babf-ca2488736e40'
      - id: '3b18fd12-c1ea-4faf-9e44-7b9158b437ca'
        name: 'Third Product Document'
        title: 'Third Product Document'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/b6deefe8-6cd5-4bcb-b7b4-116891bc6019/products/3b18fd12-c1ea-4faf-9e44-7b9158b437ca'
      - id: '1089516f-d7bf-4850-b7e0-7a6ca18c4383'
        name: 'Fourth Product Document'
        title: 'Fourth Product Document'
        version: '1.0.0'
        document: 'https://test.ibm.com/api/catalogs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/b6deefe8-6cd5-4bcb-b7b4-116891bc6019/products/1089516f-d7bf-4850-b7e0-7a6ca18c4383'
    progress: 100
    reports:
      - created_at: '2024-09-05T09:24:39.784Z'
        report_url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/scan-reports/ae166497-b64f-47e7-a23c-5e75d19adbde'
        scan_result:
          hints: '0'
          infos: '0'
          errors: '2'
          warnings: '0'
      - created_at: '2024-09-05T09:24:17.561Z'
        report_url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/scan-reports/2d86ca39-56ee-4e2f-adb8-b5b1e5e294a0'
        scan_result:
          hints: '0'
          infos: '0'
          errors: '2'
          warnings: '0'
    scan_result: '2 Errors, 0 Warnings, 0 Infos, 0 Hints, 1 Rulesets'
    status: 1
    created_at: '2024-09-05T09:24:08.000Z'
    updated_at: '2024-09-05T09:24:39.000Z'
    url: 'https://test.ibm.com/governance/orgs/6d3d9ffa-37e3-4da7-be6b-a1c34b41476f/scans/ddc5da81-0db0-425c-b74c-5fc8300934e6'

Donde " scan_type: '1' " se refiere a un escaneo de API, y " scan_type: '2' " se refiere a un escaneo de producto.

Los siguientes parámetros opcionales le permiten refinar los resultados de este mandato.

--status status_number es una lista separada por comas de códigos de estado por los que filtrar la lista de exploraciones.

Tabla 1. Tabla de códigos de estado válidos

Código Estado

0 En cola

1 Completado

2 En curso

-1 Error
--type catalog_or_space lista las exploraciones que son del tipo catalog o space.
--scan_type api_or_product es una bandera opcional para listar específicamente los escaneos de sólo APIs o sólo productos. Utilice el valor " api " para listar sólo los escaneos de API, o " product " para listar sólo los escaneos de producto. Si se omite, se enumeran tanto las exploraciones de API como las de tipo de producto.
--collections list_of_collections es una lista separada por comas de ID o nombres de catálogo o espacio por los que filtrar la lista de exploraciones.
--limit number_of_results especifica cuántos resultados de exploración se deben devolver.

Tabla 1. Tabla de códigos de estado válidos
Código	Estado
`0`	En cola
`1`	Completado
`2`	En curso
`-1`	Error

--fields list_of_fields es una lista separada por comas de nombres de campo a devolver. Tenga en cuenta que no se permiten espacios después de una coma, y si desea devolver sólo un campo, debe omitir la coma. Por ejemplo, ejecutando el mandato siguiente:

apic --mode governance scans:list --scope org --org <target_org> --server <platform_api_host_name> --fields id,title

Devuelve los datos de la forma siguiente:

total_results: 2
results:
  - id: 'e0b8afbd-e5fa-486e-8800-343e1e31faf1'
    title: 'e0b8afbd-e5fa-486e-8800-343e1e31faf2'
  - id: '436d9db5-ea45-4d91-96c4-cef5957a2c34'
    title: '436d9db5-ea45-4d91-96c4-cef5957a2c34'

Por ejemplo:

apic --mode governance scans:list --scope org --org demo -s test.ibm.com --collections cat1 --type catalog --status 1

Obtener una exploración específica utilizando el comando scans:get:
```
apic --mode governance scans:get --scope org --org <target_org> --server <platform_api_host_name> SCAN
```
Donde:
- scope es el ámbito de la exploración y debe establecerse en org para una exploración de validación de catálogo o espacio.
- <target_org> es el nombre de la organización de proveedores que contiene la exploración que desea obtener.
- <platform_api_host_name> es la parte del nombre de host URL del servidor que aloja el Gestor de API (el "servidor de gestión").
  
  Consejo: Para determinar el nombre de host, puede abrir el Gestor de API en un navegador y copiar el nombre de host de la URL en la barra de direcciones (empezando después de https:// y terminando antes de /manager ).
- SCAN es el ID o nombre de la exploración que se desea recuperar.
Los resultados de la exploración se descargan en el directorio donde se ha ejecutado el mandato.
Actualice las propiedades de exploración title y summary creando un SCAN_FILE con la información que se va a actualizar y ejecutando el mandato scans:update .
```
apic --mode governance scans:update --scope org --org <target_org> --server <platform_api_host_name> SCAN SCAN_FILE
```
Donde:
- scope es el ámbito de la exploración y debe establecerse en org para una exploración de validación de catálogo o espacio.
- <target_org> es el nombre de la organización de proveedores que contiene la exploración que desea actualizar.
- <platform_api_host_name> es la parte del nombre de host URL del servidor que aloja el Gestor de API (el "servidor de gestión").
  
  Consejo: Para determinar el nombre de host, puede abrir el Gestor de API en un navegador y copiar el nombre de host de la URL en la barra de direcciones (empezando después de https:// y terminando antes de /manager ).
- SCAN es el ID o nombre del escaneo que desea actualizar.
- SCAN_FILE es la vía de acceso a un archivo JSON que contiene las propiedades que se van a actualizar.
SCAN_FILE puede contener las propiedades siguientes:
```
{
  "title": "<updated_title>",
  "summary": "<updated_summary>"
}
```
Suprima un escaneo utilizando el mandato scans:delete . Este mandato suprime la exploración especificada y todos sus informes.
```
apic --mode governance scans:delete --scope org --org <target_org> --server <platform_api_host_name> SCAN
```
Donde SCAN es el ID o el nombre del escaneo que desea actualizar.
Suprima todas las exploraciones de una organización de proveedores determinada utilizando el mandato scans:clear . Este mandato borra todas las exploraciones y todos sus informes para la organización especificada.
```
apic --mode governance scans:clear --scope org --org <target_org> --server <platform_api_host_name> --confirm organisation_confirmed
```
Donde organisation_confirmed es el nombre de la organización de proveedores de nuevo, para confirmar que desea borrar todas las exploraciones de esta organización.

Ejecución de mandatos scan-reports

Los mandatos siguientes detallan cómo gestionar y actualizar los informes de exploración.

Liste todos los informes de exploración para una organización de proveedores determinada utilizando el mandato scan-reports:list .
```
apic --mode governance scan-reports:list --scope org --org <target_org> --server <platform_api_host_name>
```
Los siguientes parámetros opcionales le permiten refinar los resultados de este mandato.
- --fields list_of_fields es una lista separada por comas de nombres de campo a devolver. Tenga en cuenta que no se permiten espacios después de una coma, y si desea devolver sólo un campo, debe omitir la coma. Por ejemplo, ejecutando el mandato siguiente:
```
apic --mode governance scan-reports:list --scope org --org <target_org> --server <platform_api_host_name> --fields id,title
```
  Devuelve los datos de la forma siguiente:
```
total_results: 2
results:
  - id: '3e3189a3-6359-4113-9cf9-9bde9f303884'
    title: '3e3189a3-6359-4113-9cf9-9bde9f303882'
  - id: '58a975cf-a503-4297-9450-237db102cb24'
    title: '58a975cf-a503-4297-9450-237db102cb24'
```
- --limit number_of_results especifica cuántos resultados de informe de exploración se deben devolver.
Obtenga un informe de exploración específico utilizando el mandato scans:get .
```
apic --mode governance scan-reports:get --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT
```
Donde SCAN_REPORT es el ID o el nombre del informe de exploración.
Los resultados del informe de exploración se descargan en el directorio donde se ha ejecutado el mandato.
Actualice la propiedad summary del informe de exploración creando un SCAN_REPORT_FILE con la información que se va a actualizar y ejecutando el mandato scan-reports:update .
```
apic --mode governance scan-reports:update --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT SCAN_REPORT_FILE
```
Donde:
- SCAN_REPORT es el ID o nombre del informe de exploración que desea actualizar.
- SCAN_REPORT_FILE es la vía de acceso a un archivo JSON que contiene las propiedades que se van a actualizar.
SCAN_REPORT_FILE puede contener las propiedades siguientes:
```
{
  "summary": "updated_summary"
}
```
Suprima un informe de exploración utilizando el mandato scan-reports:delete . Este mandato suprime el informe de exploración especificado y elimina la referencia al mismo del escaneo. Tenga en cuenta que no puede suprimir el último informe de un escaneo. Si desea suprimir todos los informes de un escaneo, debe suprimir el propio escaneo utilizando el mandato scans:delete .
```
apic --mode governance scan-reports:delete --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT
```
Donde SCAN_REPORT es el ID o el nombre del informe de exploración que desea suprimir.