Utilisation de l' interface de ligne de commande du kit d'outils pour analyser vos catalogues et vos espaces

Modifier en ligne

Comment utiliser IBM® API Connect interface CLI du kit pour exécuter des analyses de validation gouvernance sur vos catalogues et vos espaces.

A propos de

API governance est un API Connect service qui peut être utilisé pour valider et appliquer les politiques de gouvernance organisationnelle et les meilleures pratiques à votre processus de développement d'API. Les informations suivantes fournissent des détails sur les commandes de l' interface de ligne de commande du kit d'outils pour l'exécution et la gestion des analyses de validation sur vos catalogues et vos espaces. Pour plus d'informations sur la numérisation de validation, consultez la section « Numérisation de vos catalogues et espaces ».

Les sections suivantes expliquent en détail comment exécuter des commandes d'analyse de validation à l'aide de l' interface de ligne de commande du kit d'outils.

ATTENTION : l'analyse de catalogues ou d'espaces contenant plus d'une centaine de documents API ou de produits, ainsi que l'utilisation d'un grand nombre de jeux de règles pour cette analyse, peuvent prendre plusieurs heures et risquent d'aboutir à un délai d'expiration avant la fin de l'opération, en fonction de la charge de travail de votre serveur. Un seul document peut être scanné à la fois, et plus le nombre d'ensembles de règles appliqués est élevé, plus chaque scannage individuel est long. Dans ce cas, il faut envisager de ne sélectionner que quelques jeux de règles pour chaque analyse.

Connexion à l' interface de ligne de commande du kit d'outils

Connectez-vous au kit d'outils en tant que propriétaire ou administrateur de votre organisation de type fournisseur.
Par exemple :
```
apic login --server platform-api-host-name --sso
```
Où <platform-api-host-name> est la portion du nom d'hôte URL du serveur qui héberge le gestionnaire API (le "serveur de gestion"). Pour déterminer le nom d'hôte, ouvrez API Manager dans un navigateur et copiez le nom d'hôte à partir de URL dans la barre d'adresse (commençant après " https:// " et se terminant avant " /manager "), comme indiqué dans l'exemple suivant :
```
https://platform-api.us-east-1.d-r01.apic.cloud.ibm.com/manager
```
Lorsque le kit d'outils vous invite à entrer le contexte, tapez provider et appuyez sur la touche Entrée :
```
Context? provider
```
Pour plus d'informations sur le CLI de la boîte à outils, voir Configuration de la boîte à outils API Connect .

Exécution des commandes compliance:scan

Les commandes suivantes expliquent en détail comment exécuter une analyse de conformité sur un catalogue ou un espace.

Créez un objet JSON COMPLIANCE_REQUEST_FILE qui spécifie l'emplacement du catalogue ou de l'espace et les ensembles de règles à utiliser lors d'une analyse de validation.
Par exemple :
```
{
  "collectionUrl": "https://server/api/catalogs/org/catalog",
  "config": {
    "rulesets": [
      {
        "rulesetName": "spectral-oas",
        "disabled": ["info-contact"]
      },
      {
        "rulesetName": "spectral-owasp",
        "disabled": []
      }
    ]
  }
}
```
Où :
- collectionUrl est l' URL du catalogue ou de l'espace qui contient les documents de l'API sur lesquels vous souhaitez effectuer un contrôle de validation, où server est l' URL du serveur, org est le nom ou l'ID de l'organisme fournisseur, et catalog est le nom ou l'ID du catalogue ou de l'espace. Par exemple : https://localhost:3003/api/catalogs/alpha/sandbox.
- rulesets contient la liste des ensembles de règles à appliquer aux API lors de l'analyse de validation.
  Pour chaque ensemble de règles de la liste, vous pouvez éventuellement ajouter la propriété disabled avec une liste délimitée par des virgules de règles à ignorer lors de la validation.
Exécutez une analyse de validation à l'aide de la commande compliance:scan .
```
apic --mode governance compliance:scan --scope org --org <target_org> --server <platform_api_host_name> COMPLIANCE_REQUEST_FILE
```
Où :
- scope est la portée de l'analyse et doit être définie sur org pour une analyse de validation de catalogue ou d'espace.
- <target_org> est le nom de l'organisation de type fournisseur qui contient le catalogue ou l'espace que vous souhaitez analyser à nouveau.
- <platform_api_host_name> est la portion du nom d'hôte de l' URL du serveur qui héberge le gestionnaire d'API (le "serveur de gestion").
  
  Conseil : pour déterminer le nom d'hôte, vous pouvez ouvrir le gestionnaire d'API dans un navigateur et copier le nom d'hôte de l' URL dans la barre d'adresse (commençant après https:// et se terminant avant /manager ).
- COMPLIANCE_REQUEST_FILE est le chemin et le nom du fichier JSON qui contient les détails de la configuration de l'analyse de validation. Par exemple, ./documents/validate-apis.json.
Cette commande lance une analyse de vos API.
Pour lancer une analyse de vos produits, vous devez ajouter le paramètre facultatif " --scan_type avec la valeur " product à la commande. Exemple :
```
apic --mode governance compliance:scan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-products.json --scan_type product
```
vous pouvez utiliser la valeur api pour analyser uniquement les API, ou product pour analyser uniquement les produits. S'il est omis, seules les API sont analysées.
Les résultats de l'analyse sont imprimés à l'écran.
Le paramètre facultatif suivant permet d'affiner les résultats de cette commande.
- --scantitle scan_title est un indicateur facultatif qui modifie le titre de l'analyse récupérée en fonction de la valeur que vous fournissez.
Exemple :
```
apic --mode governance compliance:scan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-apis.json --scantitle scan1
```
Réexécutez une analyse de validation existante à l'aide de la commande compliance:rescan .
Une réexécution d'examen crée un nouveau rapport pour cet examen, mais utilise la même configuration de catalogue ou d'espace et d'ensembles de règles que celle utilisée lors de l'examen précédent.
```
apic --mode governance compliance:rescan --scope org --org <target_org> --server <platform_api_host_name> --scan <scan_name_or_scan_id>
```
Où :
- scope est la portée de l'analyse et doit être définie sur org pour une analyse de validation de catalogue ou d'espace.
- <target_org> est le nom de l'organisation de type fournisseur qui contient le catalogue ou l'espace que vous souhaitez analyser à nouveau.
- <platform_api_host_name> est la portion du nom d'hôte de l' URL du serveur qui héberge le gestionnaire d'API (le "serveur de gestion").
  
  Conseil : pour déterminer le nom d'hôte, vous pouvez ouvrir le gestionnaire d'API dans un navigateur et copier le nom d'hôte de l' URL dans la barre d'adresse (commençant après https:// et se terminant avant /manager ).
- scan_name_or_scan_id est le nom ou l'ID de l'examen existant que vous souhaitez réexécuter.
Le paramètre facultatif suivant permet d'affiner les résultats de cette commande.
- --scantitle scan_title est un indicateur facultatif qui modifie le titre du rescan en fonction de la valeur que vous fournissez.
Par exemple :
```
apic --mode governance compliance:rescan --scope org --org my_org --server my_platform_api_host_name ./documents/validate-apis.json --scantitle scan2
```

Exécution des commandes scans

Les commandes suivantes expliquent en détail comment gérer et mettre à jour vos analyses de validation.

Répertoriez toutes les analyses de validation qui existent pour une organisation de type fournisseur spécifique à l'aide de la commande scans:list .

Le retour inclut des informations sur toutes les analyses de validation et des informations sur leurs rapports d'analyse, mais si vous souhaitez obtenir des informations plus détaillées sur les rapports, utilisez la commande scan-reports:list .

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

Où :

scope est la portée de l'analyse et doit être définie sur org pour une analyse de validation de catalogue ou d'espace.
<target_org> est le nom de l'organisation de type fournisseur pour laquelle vous souhaitez obtenir une liste d'analyses.
<platform_api_host_name> est la portion du nom d'hôte de l' URL du serveur qui héberge le gestionnaire d'API (le "serveur de gestion").

Conseil : pour déterminer le nom d'hôte, vous pouvez ouvrir le gestionnaire d'API dans un navigateur et copier le nom d'hôte de l' URL dans la barre d'adresse (commençant après https:// et se terminant avant /manager ).

L'exemple suivant montre la sortie d'une liste contenant deux analyses, l'une des API et l'autre des produits :

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'

Où " scan_type: '1' fait référence à une analyse de l'API et " scan_type: '2' à une analyse du produit.

Les paramètres facultatifs suivants vous permettent d'affiner les résultats de cette commande.

--status status_number est une liste de codes de statut séparés par des virgules pour filtrer la liste des analyses.

Tableau 1. Tableau des codes d'état valides

Coder Statut

0 En file d'attente

1 Terminé

2 En cours

-1 Erreur
--type catalog_or_space répertorie les analyses de type catalog ou space.
--scan_type api_or_product est un indicateur facultatif qui permet de répertorier spécifiquement les analyses portant uniquement sur les API ou uniquement sur les produits. Utilisez la valeur " api pour ne répertorier que les analyses d'API, ou " product pour ne répertorier que les analyses de produits. S'il est omis, les analyses de l'API et du type de produit sont répertoriées.
--collections list_of_collections est une liste d'ID ou de noms de catalogue ou d'espace séparés par des virgules pour filtrer la liste des analyses.
--limit number_of_results indique le nombre de résultats d'analyse à renvoyer.

Tableau 1. Tableau des codes d'état valides
Coder	Statut
`0`	En file d'attente
`1`	Terminé
`2`	En cours
`-1`	Erreur

--fields list_of_fields est une liste de noms de zone séparés par des virgules à renvoyer. Notez qu'aucun espace n'est autorisé après une virgule et que si vous ne souhaitez renvoyer qu'une seule zone, vous devez omettre la virgule. Par exemple, en exécutant la commande suivante:

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

Renvoie les données de la manière suivante:

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'

Par exemple :

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

Obtenir un scan spécifique en utilisant la commande scans:get :
```
apic --mode governance scans:get --scope org --org <target_org> --server <platform_api_host_name> SCAN
```
Où :
- scope est la portée de l'analyse et doit être définie sur org pour une analyse de validation de catalogue ou d'espace.
- <target_org> est le nom de l'organisation de type fournisseur qui contient l'analyse que vous souhaitez obtenir.
- <platform_api_host_name> est la portion du nom d'hôte de l' URL du serveur qui héberge le gestionnaire d'API (le "serveur de gestion").
  
  Conseil : pour déterminer le nom d'hôte, vous pouvez ouvrir le gestionnaire d'API dans un navigateur et copier le nom d'hôte de l' URL dans la barre d'adresse (commençant après https:// et se terminant avant /manager ).
- SCAN est l'ID ou le nom de l'analyse que vous souhaitez récupérer.
Les résultats de l'analyse sont téléchargés dans le répertoire où la commande a été exécutée.
Mettez à jour les propriétés d'analyse title et summary en créant un SCAN_FILE avec les informations à mettre à jour et en exécutant la commande scans:update .
```
apic --mode governance scans:update --scope org --org <target_org> --server <platform_api_host_name> SCAN SCAN_FILE
```
Où :
- scope est la portée de l'analyse et doit être définie sur org pour une analyse de validation de catalogue ou d'espace.
- <target_org> est le nom de l'organisation de type fournisseur qui contient l'examen que vous souhaitez mettre à jour.
- <platform_api_host_name> est la portion du nom d'hôte de l' URL du serveur qui héberge le gestionnaire d'API (le "serveur de gestion").
  
  Conseil : pour déterminer le nom d'hôte, vous pouvez ouvrir le gestionnaire d'API dans un navigateur et copier le nom d'hôte de l' URL dans la barre d'adresse (commençant après https:// et se terminant avant /manager ).
- SCAN est l'ID ou le nom de l'examen que vous souhaitez mettre à jour.
- SCAN_FILE est le chemin d'accès à un fichier JSON qui contient les propriétés à mettre à jour.
SCAN_FILE peut contenir les propriétés suivantes:
```
{
  "title": "<updated_title>",
  "summary": "<updated_summary>"
}
```
Supprimez un examen à l'aide de la commande scans:delete . Cette commande supprime l'analyse spécifiée et tous ses rapports.
```
apic --mode governance scans:delete --scope org --org <target_org> --server <platform_api_host_name> SCAN
```
Où SCAN est l'ID ou le nom de l'analyse à mettre à jour.
Supprimez toutes les analyses d'une organisation de type fournisseur particulière à l'aide de la commande scans:clear . Cette commande efface tous les examens et tous leurs rapports pour l'organisation spécifiée.
```
apic --mode governance scans:clear --scope org --org <target_org> --server <platform_api_host_name> --confirm organisation_confirmed
```
Où organisation_confirmed est à nouveau le nom de l'organisation de type fournisseur, pour confirmer que vous souhaitez effacer tous les examens de cette organisation.

Exécution des commandes scan-reports

Les commandes suivantes expliquent en détail comment gérer et mettre à jour vos rapports d'analyse.

Répertoriez tous les rapports d'analyse d'une organisation de type fournisseur particulière à l'aide de la commande scan-reports:list .
```
apic --mode governance scan-reports:list --scope org --org <target_org> --server <platform_api_host_name>
```
Les paramètres facultatifs suivants vous permettent d'affiner les résultats de cette commande.
- --fields list_of_fields est une liste de noms de zone séparés par des virgules à renvoyer. Notez qu'aucun espace n'est autorisé après une virgule et que si vous ne souhaitez renvoyer qu'une seule zone, vous devez omettre la virgule. Par exemple, en exécutant la commande suivante:
```
apic --mode governance scan-reports:list --scope org --org <target_org> --server <platform_api_host_name> --fields id,title
```
  Renvoie les données de la manière suivante:
```
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 indique le nombre de résultats de rapport d'analyse à renvoyer.
Obtenez un rapport d'analyse spécifique à l'aide de la commande scans:get .
```
apic --mode governance scan-reports:get --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT
```
Où SCAN_REPORT est l'ID ou le nom du rapport d'analyse.
Les résultats du rapport d'analyse sont téléchargés dans le répertoire où la commande a été exécutée.
Mettez à jour la propriété summary du rapport d'analyse en créant un SCAN_REPORT_FILE avec les informations à mettre à jour et en exécutant la commande scan-reports:update .
```
apic --mode governance scan-reports:update --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT SCAN_REPORT_FILE
```
Où :
- SCAN_REPORT est l'ID ou le nom du rapport d'analyse que vous souhaitez mettre à jour.
- SCAN_REPORT_FILE est le chemin d'accès à un fichier JSON qui contient les propriétés à mettre à jour.
SCAN_REPORT_FILE peut contenir les propriétés suivantes:
```
{
  "summary": "updated_summary"
}
```
Supprimez un rapport d'analyse à l'aide de la commande scan-reports:delete . Cette commande supprime le rapport d'analyse spécifié et supprime la référence à ce rapport de l'analyse. Notez que vous ne pouvez pas supprimer le dernier rapport d'un examen. Si vous souhaitez supprimer tous les rapports d'une analyse, vous devez supprimer l'analyse elle-même à l'aide de la commande scans:delete .
```
apic --mode governance scan-reports:delete --scope org --org <target_org> --server <platform_api_host_name> SCAN_REPORT
```
Où SCAN_REPORT est l'ID ou le nom du rapport d'analyse à supprimer.