Configurazione di governance in API Manager

Modifica online

Come aggiungere regole di governance personalizzate al processo di sviluppo delle API per convalidare e applicare le politiche di governance organizzativa e le best practice nella vostra organizzazione di provider.

Prima di iniziare

Uno dei seguenti ruoli è richiesto per poter configurare la governance:

Amministratore organizzazione
Proprietario
Ruolo personalizzato con l'autorizzazione Settings: Manage .

Informazioni su questa attività

Il servizio di governance è un componente aggiuntivo di IBM® API Connect che può essere utilizzato per convalidare e applicare le politiche di governance organizzativa e le best practice nel processo di sviluppo delle API. La governance si configura creando uno o più insiemi di regole personalizzate che contengono un insieme di regole che possono essere utilizzate per controllare i documenti Swagger, OpenAPI, e AsyncAPI, nonché i documenti dei prodotti. È inoltre possibile eseguire scansioni di convalida sui propri cataloghi e spazi; per ulteriori informazioni, consultare la sezione "Scansione dei cataloghi e degli spazi".

Il servizio governance contiene i seguenti tipi di serie di regole:

Services

Serie di regole dell'organizzazione provider - sono serie di regole personalizzate che contengono le regole create e specifiche per l'organizzazione provider per la convalida delle API.
Serie di regole globali - queste sono serie di regole IBM e Spectral preconfigurate che contengono le regole condivise con la tua organizzazione provider per la convalida delle API e non possono essere modificate. I nomi dei ruleset di Spectral hanno il prefisso spectral- e la loro versione corrisponde alla versione di quel ruleset disponibile in Spectral.

Prodotto

Serie di regole dell'organizzazione provider - si tratta di serie di regole personalizzate che contengono le regole create e specifiche dell'organizzazione provider per convalidare i prodotti.
Serie di regole globali - si tratta di serie di regole personalizzate preconfigurate che contengono le regole condivise con l'organizzazione provider per la convalida dei prodotti e che non possono essere modificate.

La governance in API Connect si basa sul linter open source Spectral; per ulteriori informazioni su Spectral, consultare il sito https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview.

È possibile aggiungere tag ai set di regole API che, se abbinati allo stesso tag in un'API, contribuiscono a garantire la preselezione dei set di regole appropriati per le scansioni di convalida. In questo modo, il processo di governance può essere gestito in modo più rapido ed efficace. Questi set di regole preselezionati possono essere deselezionati dalla scansione, se necessario.

Nota:

La governance in API Connect supporta la creazione di set di regole personalizzati che contengono regole che utilizzano esclusivamente le funzioni di base integrate di Spectral, come definito in https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions. L'uso di funzioni personalizzate, ad esempio regole che utilizzano funzioni create dall'utente in file JavaScript, non è supportato. Inoltre, le seguenti regole Spectral OpenAPI non sono supportate perché potrebbero identificare falsi positivi:
- oas2-unused-definition
- oas3-unused-component
Alcune delle regole Spectral all'interno di Serie di regole globali contengono la proprietà recommended: false, il che significa che tali regole vengono ignorate durante la convalida. Tuttavia, se si crea una nuova serie di regole da una di queste serie di regole utilizzando l'opzione Salva come nuova serie di regole , la proprietà recommended non viene trasferita alla nuova serie di regole. Pertanto, tutte le regole vengono utilizzate nella convalida, a meno che non vengano eliminate dal set di regole. I nomi dei set di regole Spectral hanno il prefisso " spectral-.
L'annullamento del riferimento, che significa non eseguire l'introspezione di una definizione di riferimento all'interno di un'API, non è supportato nel servizio governance . Invece, un oggetto di riferimento può essere esplicitamente convalidato utilizzando regole personalizzate.

I metodi seguenti possono essere utilizzati per configurare sia l'API che le serie di regole del prodotto:

Crea una nuova serie di regole utilizzando l'interfaccia utente
Importare una serie di regole
Crea una serie di regole utilizzando la CLI

Procedura

Per creare una nuova API o serie di regole del prodotto utilizzando l'IU API Manager o API Designer , completa la seguente procedura.

Nella barra dei menu laterale, clicca su Governance.
Viene visualizzata la pagina Governance .
Se vuoi creare una serie di regole API, fai clic sulla scheda API . Se si desidera creare una serie di regole del prodotto, fare clic sulla scheda Prodotto .
Viene visualizzata la pagina di gestione delle serie di regole.
Nella sezione " Set di regole dell'organizzazione del provider ", fare clic su Aggiungi > Crea da zero.
Viene aperta la procedura guidata Crea serie di regole dell'organizzazione provider .

Fornire i seguenti dettagli Informazioni serie di regole .

Etichetta proprietà	Obbligatorio	Descrizione	Tipo di dati
Titolo	Vero	Un nome descrittivo breve per la serie di regole. Questo nome viene visualizzato nell'elenco di serie di regole globali.	Stringa
Nome	Vero	Una stringa generata automaticamente, lenta, basata sul titolo. Non può essere modificato.	Stringa
Versione	Vero	Il numero di versione è impostato su 1.0.0, ma può essere modificato. È possibile avere serie di regole con lo stesso nome, ma con numeri di versione differenti. Il numero di versione deve essere nel formato `major.minor.patch`.	Stringa
Descrizione	N	Una descrizione facoltativa della serie di regole.	Stringa

Facoltativo: per i set di regole API, è possibile aggiungere uno o più tag al proprio set di regole facendo clic su Aggiungi e compilando i campi Nome e Descrizione del tag.
L'aggiunta di tag corrispondenti ai set di regole e alle API significa che le scansioni di convalida possono preselezionare i set di regole da utilizzare per la scansione. Tuttavia, è possibile sovrascrivere questa preselezione con set di regole a scelta. Per ulteriori informazioni su come aggiungere tag alle API, vedere Aggiunta di tag a un'API.
Fare clic su Avanti, quindi aggiungere una regola iniziale alla serie di regole.

Fornire i seguenti dettagli Informazioni sulla regola .

Etichetta proprietà	Obbligatorio	Descrizione	Tipo di dati
Titolo	Vero	Un nome descrittivo breve per la regola.	Stringa
Nome	Vero	Una stringa generata automaticamente, lenta, basata sul titolo. Non può essere modificato.	Stringa
Descrizione	Vero	Una descrizione della regola.	Stringa
Messaggio	N	Fornire un messaggio per aiutare gli utenti a capire quale sia l'obiettivo della regola. Se non viene fornito alcun messaggio, il valore della proprietà Descrizione viene utilizzato per l'output del messaggio della scansione di convalida.	Stringa
Severità	Vero	Selezionare un livello di severità dalle opzioni seguenti: Errore avvertenza informazioni suggerimento non attivo errore è selezionato per impostazione predefinita.	Stringa

Nella sezione Dato , specificare uno o più valori per le parti dell'API o del documento del prodotto di destinazione. Per aggiungere ulteriori valori, fare clic su Aggiungi. I valori devono essere scritti in JSONPath.
Nella sezione Then , specificare il tipo di funzione e le opzioni che verranno utilizzate per valutare i valori di destinazione nel documento API o prodotto. Scrivere questa sezione nella YAML sintassi.
Nel seguente esempio di regola API, per un valore Dato di $ (che indica il livello root del documento), la sezione Then utilizza la funzione Spectral core truthy per controllare che il valore della proprietà info.contact non sia false, "", 0, nullo undefined.
```
- field: info.contact
  function: truthy
```
La sezione Quindi può contenere anche un elenco di funzioni da applicare alla parte Dati del documento. Nel seguente esempio di regola API, per un valore Dato di $.info.version (che fa riferimento alla proprietà version all'interno della proprietà info al livello root del documento), la sezione Then utilizza sia la funzione truthy che la funzione Spectral core pattern che controlla che info.value corrisponda all'espressione regex fornita da functionOptions.match.
```
- function: truthy
- function: pattern
  functionOptions:
    match: "^[0-9]+.[0-9]+.[0-9]+(-[a-z0-9+.-]+)?"
```
Per un elenco completo delle funzioni principali di Spectral che è possibile utilizzare nelle regole API personalizzate, insieme ad alcuni esempi di tali funzioni, consultare https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions.
Fare clic su Crea per creare la serie di regole bozza.
La serie di regole bozza viene aperta nella vista del modulo di progettazione. Si noti che è possibile passare alla visualizzazione del codice sorgente YAML di OpenAPI facendo clic sull'icona "Sorgente ". Per tornare alla visualizzazione del modulo di progettazione, clicca sull'icona Modulo.
Ora sono disponibili le seguenti opzioni:
- È possibile continuare a modificare la serie di regole. Ad esempio, puoi aggiungere altre regole cliccando sull'icona Crea regola accanto alla voce Regole nella pagina di navigazione. Fare clic su Salva una volta terminata la modifica.
- Se non vuoi modificare ulteriormente la tua serie di regole ora, fai clic su Governance nella traccia di navigazione per tornare alla pagina di panoramica API governance .

Per importare un'API esistente o una serie di regole del prodotto, completa la seguente procedura. Le regole contenute nel set di regole importato possono includere solo funzioni di base integrate di Spectral, come definito all'indirizzo https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions.
1. Nella barra dei menu laterale, clicca su Governance.
  Viene visualizzata la pagina Governance .
2. Se vuoi creare una serie di regole API, fai clic sulla scheda API . Se si desidera creare una serie di regole del prodotto, fare clic sulla scheda Prodotto .
  Viene visualizzata la pagina di gestione delle serie di regole.
3. Nella sezione "Set di regole dell'organizzazione del fornitore ", fare clic su Aggiungi > Importa.
  Viene aperta la procedura guidata Importa serie di regole .
4. Trascinare un file nella casella Carica file oppure fare clic nella casella Carica file per selezionare un file da caricare. La dimensione file massima è 100 kb e i tipi di file supportati sono YAML, YML e JSON.
5. Fare clic su Avanti.
6. Modificare i dettagli Informazioni sulla serie di regole come richiesto e fare clic su Importa.
  La serie di regole bozza viene aperta nella vista del modulo di progettazione. Si noti che è possibile passare alla visualizzazione del codice sorgente YAML di OpenAPI facendo clic sull'icona "Sorgente ". Per tornare alla visualizzazione del modulo di progettazione, clicca sull'icona Modulo.
7. Ora sono disponibili le seguenti opzioni:
  - È possibile continuare a modificare la serie di regole. Ad esempio, puoi aggiungere altre regole cliccando sull'icona Crea regola accanto alla voce Regole nella pagina di navigazione. Fare clic su Salva una volta terminata la modifica.
  - Se non vuoi modificare ulteriormente la tua serie di regole ora, fai clic su Governance nella traccia di navigazione per tornare alla pagina di panoramica API governance .

Per creare un'API o una serie di regole del prodotto utilizzando la CLI del toolkit, completa la seguente procedura.

Creare un file JSON contenente il nuovo set di regole.

Il seguente JSON mostra il contenuto di un file della serie di regole Spectral del documento API di esempio:

{
    "name": "short-draft-ootb",
    "title": "short-draft-ootb",
    "description": "short ruleset",
    "ruleset_type": "custom",
    "tags": [
      {
        "name": "general",
        "description": "general work"
      }
    ]
    "rules": [
      {
        "name": "sec-array-boundaries-2",
        "description": "Array size should be limited to mitigate resource exhaustion attacks.\nThis can be done using `maxItems` and `minItems`, like in the example\nbelow.\n\n```\nLimited:\n  type: array\n  maxItems: 10\n  items:\n    type: string\n    format: date\n```\n\nYou should ensure that the schema referenced in  `items` is constrained too.\n\nIf you delegate input validation to a library or framework,\nbe sure to test it thoroughly and ensure that it verifies `maxItems`.",
        "message": "Schema of type array must specify maxItems and minItems. {{path}} {{error}}",
        "formats": [
          "oas3"
        ],
        "severity": "warn",
        "recommended": true,
        "given": [
          "$..[?(@.type==\"array\")]"
        ],
        "then": [
          {
            "field": "maxItems",
            "function": "defined"
          }
        ]
      }
    ]
  }

Il seguente JSON visualizza il contenuto di un file della serie di regole del documento del prodotto di esempio:

{
  "type": "ruleset",
  "ruleset_type": "custom",
  "api_version": "2.0.0",
  "id": "dbb5f400-e707-412e-b081-ac36f5afbbb9",
  "name": "test-product",
  "title": "Test Product",
  "description": "",
  "ruleset_version": "1.0.0",
  "ruleset_state": "draft",
  "ruleset_format_type": "2",
  "rule_urls": [
    "https://my.manager.com/governance/orgs/myorg/rulesets/1.0.0-test-product/rules/ca6ef7d9-a503-498e-8f53-4e3aa35d086b"
  ],
  "created_at": "2024-05-22T17:19:02.820Z",
  "updated_at": "2024-05-22T17:24:59.000Z",
  "url": "https://my.manager.com/governance/orgs/myorg/rulesets/dbb5f400-e707-412e-b081-ac36f5afbbb9",
  "rules": [
    {
      "api_version": "2.0.0",
      "id": "ca6ef7d9-a503-498e-8f53-4e3aa35d086b",
      "name": "subscribe",
      "version": "1.0.0",
      "title": "subscribe",
      "description": "subscribe enabled",
      "message": "subscribe not enabled",
      "given": [
        "$.visibility.subscribe.enabled"
      ],
      "severity": "error",
      "created_at": "2024-05-22T17:19:02.000Z",
      "updated_at": "2024-05-22T17:24:59.000Z",
      "url": "https://my.manager.com/governance/orgs/myorg/rulesets/1.0.0-test-product/rules/ca6ef7d9-a503-498e-8f53-4e3aa35d086b",
      "then": [
        {
          "function": "pattern",
          "functionOptions": {
            "notMatch": "/true"
          }
        }
      ]
    }
  ]
}

Accedere al toolkit come proprietario o amministratore dell'organizzazione di provider che possiede il nuovo set di regole.
Ad esempio:
```
apic login --server platform-api-host-name --sso
```
Dove <platform-api-host-name> è la porzione di hostname URL del server che ospita API Manager (il "server di gestione"). Per determinare l'hostname, aprire API Manager in un browser e copiare l'hostname da URL nella barra degli indirizzi (iniziando dopo " https:// " e terminando prima di "/manager") come mostrato nell'esempio seguente:
```
https://platform-api.us-east-1.d-r01.apic.cloud.ibm.com/manager
```
Quando il toolkit richiede il contesto, digitate provider e premete Invio:
```
Context? provider
```
Per ulteriori informazioni sulla CLI del toolkit, vedere Impostazione del toolkit API Connect .
Eseguire il comando del toolkit rulesets:create in modalità governance :
```
apic -m governance rulesets:create --org <target_org> --server <server_url> RULESET_FILE
```
dove:
- <target_org> è il nome dell'organizzazione proprietaria della nuova serie di regole.
- <server_url> è l' URL del server di gestione che si usa per accedere al toolkit.
- RULESET_FILE è il percorso e il nome del file JSON che contiene il set di regole.

Risultati

La tua API bozza o serie di regole del prodotto è ora elencata nella tabella di Serie di regole dell'organizzazione provider.

Cosa fare successivamente

Una volta terminata la modifica della serie di regole, è possibile pubblicarla nella propria organizzazione provider. Fai clic sull'icona del menu delle opzioni accanto al set icona menu opzioni di tre punti verticali di regole che desideri pubblicare oppure all'interno del visualizzatore dei set di regole. Selezionare Pubblica, quindi fare di nuovo clic su Pubblica per confermare. Lo stato della tua serie di regole cambia da Bozza a Pubblicatae può essere ora utilizzata dagli sviluppatori per convalidare i loro documenti API e prodotto. Per ulteriori informazioni, vedere Convalida di un documento API tramite la governance.

Per convalidare un documento API o un prodotto utilizzando un set di regole pubblicato, fare clic su Convalida, selezionare le API o i prodotti da convalidare, quindi selezionare i set di regole e le regole che si desidera utilizzare e fare nuovamente clic su Convalida. Se l'API che si desidera convalidare include un tag che ha un tag corrispondente in uno o più set di regole, tali set di regole vengono selezionati automaticamente per la scansione. Tuttavia, è possibile modificare la selezione delle regole in base alle proprie esigenze. I risultati della convalida vengono visualizzati in una scorecard.

È inoltre possibile eseguire scansioni di convalida sui propri cataloghi e spazi; per ulteriori informazioni, consultare la sezione "Scansione dei cataloghi e degli spazi".

Nota:

Dopo la pubblicazione di una serie di regole, le regole e le relative informazioni non possono essere più modificate. Se devi aggiornare queste informazioni, devi creare una nuova versione cliccando sull'icona del menu delle opzioni, situata accanto al set di regole che desideri modificare oppure all'interno del visualizzatore dei set di regole, e selezionando "Salva come nuovo set di regole ".