API マネージャーでのガバナンスの構成

API開発プロセスにカスタムガバナンスルールセットを追加して、プロバイダー組織における組織ガバナンスポリシーとベストプラクティスを検証・実施する方法。

開始前に

ガバナンスを構成するには、以下のいずれかの役割が必要です。

組織の管理者
所有者
Settings: Manage 権限を持つカスタム役割。

このタスクについて

ガバナンス・サービスは、API 開発プロセスで組織のガバナンス・ポリシーおよびベスト・プラクティスを検証および適用するために使用できる IBM® API Connect のアドオンです。設定するガバナンスSwaggerをチェックするために使用できるルールのコレクションを含む1つ以上のカスタムルールセットを作成することにより、OpenAPI,そしてAsyncAPIドキュメント、および製品ドキュメント。また、カタログやスペースに対してバリデーションスキャンを実行することもできます。詳細はカタログとスペースのスキャンを参照してください。

ガバナンス・サービスには、以下のタイプのルール・セットが含まれています。

API

プロバイダー組織ルール・セット -これらは、API を検証するためにプロバイダー組織内で作成され、プロバイダー組織に固有のルールを含むカスタム・ルール・セットです。
グローバル・ルール・セット -これらは、事前構成された IBM ルール・セットおよび「スペクトル」ルール・セットです。これらのルール・セットには、API を検証するためにプロバイダー組織と共有されるルールが含まれており、編集することはできません。 Spectral のルールセット名の先頭には spectral- が付いており、そのバージョンは Spectral で利用可能なルールセットのバージョンと一致している。

製品

プロバイダー組織ルール・セット -これらは、製品を検証するためにプロバイダー組織で作成され、プロバイダー組織に固有のルールを含むカスタム・ルール・セットです。
グローバル・ルール・セット -これらは、製品を検証するためにプロバイダー組織と共有されるルールを含む事前構成済みのカスタム・ルール・セットであり、編集することはできません。

API Connectのガバナンスは、オープンソースのSpectralリンターをベースにしている。Spectralについての詳細は、https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview

タグはAPIルールセットに追加することができ、API内の同じタグとマッチすると、検証スキャンに適切なルールセットが事前に選択されるようになる。こうすることで、ガバナンス・プロセスをより迅速かつ効果的に進めることができる。これらの事前選択されたルールセットは、必要に応じてスキャンから選択解除することができる。

注:

API Connect」のガバナンスは、https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions で定義されているように、組み込みのSpectralコア機能のみを使用するルールを含むカスタムルールセットの作成をサポートします。カスタム関数の使用、たとえばJavaScriptファイルで独自に作成した関数を使用するルールはサポートされていません。また、以下の Spectral OpenAPI ルールは、偽陽性を識別する可能性があるため、サポートされていません：
- oas2-unused-definition
- oas3-unused-component
グローバル・ルール・セット内の一部の「スペクトル」ルールには、プロパティー recommended: falseが含まれています。これは、これらのルールが検証時に無視されることを意味します。ただし、「新規ルール・セットとして保存」オプションを使用してこれらのルール・セットのいずれかから新規ルール・セットを作成した場合、 recommended プロパティーは新規ルール・セットに転送されません。したがって、ルールセットからそれらのルールを削除しない限り、すべてのルールがバリデーションに使用される。 Spectral のルールセット名は、先頭に 'spectral- が付く。
参照されている定義を API 内でイントロスペクトしないことを意味する逆参照は、 governance サービスではサポートされていません。代わりに、カスタム・ルールを使用して、参照されるオブジェクトを明示的に検証することができます。

以下のメソッドを使用して、API と製品の両方のルール・セットを構成できます。

UI を使用した新規ルール・セットの作成
ルール・セットのインポート
CLI を使用したルール・セットの作成

手順

API Manager または API Designer UI を使用して新しい API ルール・セットまたは製品ルール・セットを作成するには、以下の手順を実行します。

サイドメニューバーで「ガバナンスをクリックする。
「ガバナンス」ページが表示されます。
API ルール・セットを作成する場合は、「API」タブをクリックします。製品ルール・セットを作成する場合は、「製品」タブをクリックします。
「ルール・セットの管理」ページが表示されます。
プロバイダ組織のルールセットセクションで、[Add ] > [Create from scratch]をクリックします。
「プロバイダー組織ルール・セットの作成」ウィザードが開きます。

以下のルール・セット情報の詳細を指定します。

プロパティー・ラベル	必須	説明	データ・タイプ
タイトル	はい	ルール・セットの短い記述名。この名前は、グローバル・ルール・セットのリストに表示されます。	ストリング
名前	はい	タイトルに基づいた、自動生成されたスラッグ化された文字列。これは編集できません。	ストリング
バージョン	はい	バージョン番号のデフォルトは 1.0.0ですが、編集することができます。名前が同じで、バージョン番号が異なるルール・セットを使用することができます。バージョン番号の形式は `major.minor.patch`でなければなりません。	ストリング
説明	いいえ	ルール・セットの説明 (オプション)。	ストリング

オプション： 'APIルールセットの場合、'追加クリックし、タグ'名称と'説明を記入することで、1つ以上のタグをルールセットに追加することができる。
ルールセットとAPIにマッチするタグを追加することは、検証スキャンがスキャンに使用するルールセットを事前に選択できることを意味する。しかし、この事前選択を、自分の好きなルールセットで上書きすることができる。 APIにタグを追加する方法の詳細については、 APIにタグを追加するを参照してください。
「次へ」をクリックしてから、ルール・セットに初期ルールを追加します。

以下のルール情報の詳細を指定します。

プロパティー・ラベル	必須	説明	データ・タイプ
タイトル	はい	ルールの簡潔な記述名。	ストリング
名前	はい	タイトルに基づいた、自動生成されたスラッグ化された文字列。これは編集できません。	ストリング
説明	はい	ルールの説明。	ストリング
メッセージ	いいえ	ルールの目的を理解するのに役立つメッセージを提供します。メッセージが指定されていない場合、妥当性検査スキャンのメッセージ出力には「説明」プロパティーの値が使用されます。	ストリング
重大度	はい	以下のオプションから重大度レベルを選択します。 error 警告 INFO ヒント OFF デフォルトでは、「エラー」が選択されています。	ストリング

「指定」セクションで、ターゲットとする API または製品文書の部分に 1 つ以上の値を指定します。さらに値を追加するには、「追加」をクリックします。値は JSONPath に書き込む必要があります。
「Then」セクションで、API または製品文書内のターゲット値を評価するために使用する関数タイプとオプションを指定します。このセクションは、 YAML 構文で記述します。
以下の API ルールの例では、「指定」値が $ (文書のルート・レベルを意味します) の場合、 Then セクションは Spectral core truthy 関数を使用して、 info.contact プロパティー値が false、 ""、 0、 null、または undefinedではないことを確認します。
```
- field: info.contact
  function: truthy
```
「Then」セクションには、文書の「指定」部分に適用される関数のリストを含めることもできます。以下の API ルールの例では、指定値が $.info.version (文書のルート・レベルで info プロパティー内の version プロパティーを参照) の場合、 Then セクションは truthy 関数と、 functionOptions.matchで指定された正規表現に info.value が一致することを検査する Spectral core pattern 関数の両方を使用します。
```
- function: truthy
- function: pattern
  functionOptions:
    match: "^[0-9]+.[0-9]+.[0-9]+(-[a-z0-9+.-]+)?"
```
カスタム API ルールで使用できるSpectralコア関数の完全なリストとこれらの関数の例については、https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions を参照してください。
「作成」をクリックして、ドラフト・ルール・セットを作成します。
ドラフト・ルール・セットが設計フォーム・ビューで開きます。ソースアイコン' をクリックすることで、OpenAPIYAML ソースビューに切り替えることができます。デザインフォームビューに戻るには、フォームアイコン '.
以下のオプションがあります。
- ルール・セットの編集を続行できます。例えば、ナビゲーション・ページの「Rules」の横にある「 Create rule」アイコン（）をクリックすると、さらにルールを追加することができる。編集が終了したら、必ず「保存」をクリックしてください。
- これ以上ルール・セットを編集しない場合は、パンくずリストで「ガバナンス」をクリックして、「API ガバナンス」概要ページに戻ります。

既存の API または製品のルール・セットをインポートするには、以下の手順を実行します。インポートされたルールセットのルールには、次のように定義された組み込みの Spectral コア関数のみを含めることができます。 https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions.
1. サイドメニューバーで「ガバナンスをクリックする。
  「ガバナンス」ページが表示されます。
2. API ルール・セットを作成する場合は、「API」タブをクリックします。製品ルール・セットを作成する場合は、「製品」タブをクリックします。
  「ルール・セットの管理」ページが表示されます。
3. プロバイダ組織のルールセット]セクションで、[追加 ] > [ インポート]をクリックします。
  「ルール・セットのインポート」ウィザードが開きます。
4. ファイルを「ファイルのアップロード」ボックスにドラッグするか、「ファイルのアップロード」ボックスをクリックしてアップロードするファイルを選択します。最大ファイル・サイズは 100 KB で、サポートされるファイル・タイプは YAML、YML、および JSON です。
5. 「次へ」をクリックします。
6. 必要に応じて「ルール・セット情報」の詳細を編集し、「インポート」をクリックします。
  ドラフト・ルール・セットが設計フォーム・ビューで開きます。ソースアイコン' をクリックすることで、OpenAPIYAML ソースビューに切り替えることができます。デザインフォームビューに戻るには、フォームアイコン '.
7. 以下のオプションがあります。
  - ルール・セットの編集を続行できます。例えば、ナビゲーション・ページの「Rules」の横にある「 Create rule」アイコン（）をクリックすると、さらにルールを追加することができる。編集が終了したら、必ず「保存」をクリックしてください。
  - これ以上ルール・セットを編集しない場合は、パンくずリストで「ガバナンス」をクリックして、「API ガバナンス」概要ページに戻ります。

ツールキット CLIを使用して API または製品のルール・セットを作成するには、以下の手順を実行します。

新しいルールセットを含むJSONファイルを作成する。

次の JSON は、サンプル API ドキュメントの Spectral ルールセットファイルの内容を示しています。

{
    "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"
          }
        ]
      }
    ]
  }

次の JSON は、サンプル製品ドキュメントルールセットファイルの内容を示しています。

{
  "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"
          }
        }
      ]
    }
  ]
}

新しいルールセットを所有するプロバイダ組織の所有者または管理者としてツールキットにログインします。
例:
```
apic login --server platform-api-host-name --sso
```
ここで、 <platform-api-host-name> は、API Managerをホストするサーバー（「管理サーバー」）のホスト名部分の URL である。ホスト名を決定するには、ブラウザでAPI Managerを開き、以下の例に示すように、アドレスバーの URL （ https:// の後で始まり、"/manager "の前で終わる）からホスト名をコピーする：
```
https://platform-api.us-east-1.d-r01.apic.cloud.ibm.com/manager
```
ツールキットからコンテキストの入力を求めるプロンプトが表示されたら、provider と入力して Enter キーを押します。
```
Context? provider
```
ツールキット CLIについて詳しくは、 API Connect ツールキットのセットアップを参照してください。
rulesets:create ツールキット・コマンドを governance モードで実行します。
```
apic -m governance rulesets:create --org <target_org> --server <server_url> RULESET_FILE
```
ここで:
- <target_org> は、新規ルール・セットを所有する組織の名前です。
- <server_url> は、ツールキットへのログインに使用する管理サーバーの URL です。
- RULESET_FILEは、ルールセットを含むJSONファイルのパスとファイル名である。

結果

これで、ドラフト API またはドラフト製品のルール・セットが「プロバイダー組織のルール・セット」の表にリストされます。

次のタスク

ルール・セットの編集が完了したら、それをプロバイダー組織に公開できます。公開したいルールセットの横にあるオプションメニューアイコン「 3 つの垂直ドットのオプション・メニュー・アイコン」をクリックするか、ルールセットビューアの中から「code1」をクリックしてください。「公開」を選択し、「公開」をもう一度クリックして確認します。ルール・セットの状況が「ドラフト」から「公開済み」に変わり、開発者が API および製品の文書を検証するために使用できるようになりました。詳細については、ガバナンスを使用したAPIドキュメントの検証を参照のこと。

公開されているルールセットを使用してAPIまたは製品ドキュメントを検証するには、［検証］をクリックし、検証するAPIまたは製品を選択してから、使用するルールセットとルールを選択し、［検証］を再度クリックします。検証したいAPIに、1つ以上のルールセットに一致するタグが含まれている場合、それらのルールセットは自動的にスキャン用に選択される。しかし、ルールセットの選択をあなたの要求に合わせて編集することができる。検証の結果がスコアカードに表示されます。

また、カタログとスペースの検証スキャンを実行することもできます。詳細については、カタログとスペースのスキャンを参照してください。

注:

ルール・セットが公開されると、ルール・セット情報およびルールは編集できなくなります。この情報を更新する必要がある場合は、編集したいルールセットの横にあるオプションメニューのアイコン「クリックするか、ルールセット・ビューアーの中から「新しいルールセットとして保存」を選択して、新しいバージョンを作成する必要がある。

API マネージャー での ガバナンス の構成

開始前に

このタスクについて

手順

結果

次のタスク

API マネージャーでのガバナンスの構成