API関連業務

オンラインで編集する

簡単なプロンプトを使用することで、APIの作成、更新、検証、公開、ダウンロード、削除、セキュリティ保護が可能です。 クライアントの認証情報を追加し、セキュリティを確認し、ガイド付きの確認ベースのコマンドを使用してAPIが公開される場所を制御します。

ドラフトAPIまたは API Connect APIを作成する

Create draft API プロンプトは、 API Connect インスタンスにドラフトを作成する。 create API Connect API 、プロンプトはドラフトをファイルとして表示し、 API Connect インスタンスにはドラフトは作成されない。 API定義は次のように提供できる：
  • Swagger ( OpenAPI 2.0 )、 OpenAPI ( 3.x )、または API Connect ドキュメントにリンクする URL。

  • API仕様を含むファイルのアップロード。

注:
  • 実行前にユーザーの確認が必要です。
  • 既存のSwagger、 OpenAPI,、または API Connect ドキュメントから作成できるのは、RESTプロキシAPIのみです。
注意: Draft API をファイルから作成する前に、ファイル中の url の値が正確で、 アプリケーションが実行されているサーバーを指していることを確認してください。 また、公開前に下書きファイルの url を更新することもできます。
  • Swagger 2.x ファイルの場合： host と basePath の値を確認してください。
  • OpenAPI 3.x ファイルの場合： servers > url の値を確認する。
  • API Connect ：上記に加えて、 x-ibm-configuration セクションの target-url の値をチェックする。

例:

プロンプト "create openapi spec "と "generate python fastapi server code "を使用してAPIファイルを生成した場合：

  • 生成されたfastapiサーバー・コードがネットワーク内のマシンで実行される場合、 url はそのマシンのホスト名またはIPアドレスを指す。

  • 生成されたfastapiサーバーコードが「アプリケーションコードのデプロイ」プロンプトを使用して IBM Code Engine にデプロイされる場合、 url は "give deployment status for the application code" プロンプトを実行したときに得られるアプリケーション URL の値です。

表 1. パラメータ
パラメーター タイプ 必須 説明 有効値 デフォルト
url ストリング オプション URL から Swagger ( OpenAPI 2.0 )、 OpenAPI ( 3.x )、または API Connect ドキュメントをダウンロードして、ドラフト API または API Connect API を作成することができます。
  • ドキュメントがYAMLの場合は、明示的に document_format: yaml。

  • 未指定の場合はデフォルトの形式：JSON。

 JSONまたはYAMLドキュメントを指す有効な URL。 url 、 input_file の両方が提供された場合、 url が優先される。 なし
input_file ファイル url 、または input_file 。 url 、 input_file の両方が提供された場合、 url が優先される。 JSONまたはYAML形式のAPI定義を含むファイル。

サポートされているドキュメントタイプ

  • スワガー ( OpenAPI 2.0 )

  • OpenAPI (3.x)

  • API Connect

 なし
gateway_type ストリング オプション API定義を作成するゲートウェイ・タイプ。
  • "datapower-api-gateway"
  • "apigw"
  • "datapower-gateway"
  • "v5gw"
  • "event-gateway"
 "datapower-api-gateway"
document_format ストリング オプション url を使用する場合の API ドキュメントのフォーマットを指定する。 "json", "yaml" "json"
以下のプロンプトを使用して、ドラフトAPIまたは API Connect APIを作成できます。
表 2. APIのドラフトを作成する、または API Connect のAPI
アクション プロンプト コマンド
APIのドラフトを作成する 
create draft api from URL
create draft api from URL and with format yaml
create draft api from URL and with format json and gateway type datapower-api-gateway
import api URL
import api @filename
create draft api using @filename
create draft api using @filename and gateway type datapower-api-gateway
 
/create_draft_api url:URL
/create_draft_api url:URL document_format:yaml
/create_draft_api url:URL document_format:json gateway_type:datapower-api-gateway
/create_draft_api input_file:@filename
/create_draft_api input_file:@filename gateway_type:datapower-api-gateway
API Connect APIを作成する 
create apiconnect api from URL
create apiconnect api from URL and with format yaml
create apiconnect api from URL and with format json and gateway type datapower-api-gateway
create apiconnect api using @filename
create apiconnect api using @filename and gateway type datapower-api-gateway
 
/create_apiconnect_api url:URL
/create_apiconnect_api url:URL document_format:yaml
/create_apiconnect_api url:URL document_format:json gateway_type:datapower-api-gateway
/create_apiconnect_api input_file:@filename
/create_apiconnect_api input_file:@filename gateway_type:datapower-api-gateway

ドラフトAPIの更新

update draft API プロンプトは、 API Connect インスタンスの既存のドラフト API を更新する。 この操作は、ドラフトAPIの名前とバージョン、および更新されたドラフトコンテンツを必要とする。 アップデートが適用される前に、ユーザーの確認が必要です。

表 3. パラメータ
パラメーター タイプ 必須 説明
api_name ストリング はい 更新するドラフトAPIの識別子。 識別子は、API名、 api_name:version、またはドラフトAPIのIDの形式で指定できる。
version ストリング いいえ ドラフトAPIのバージョン。
input_file ファイル はい 更新されたAPI定義を含むファイル。 このファイルは、JSONまたはYAML形式の、 API Connect -固有の OpenAPI ドキュメントでなければならない。 このファイルは、既存のドラフトAPIコンテンツを上書きするために使用される。
以下のプロンプトを使用して、ドラフトAPIを更新することができる。
表 4。 APIのドラフトを更新する
アクション プロンプト コマンド
APIのドラフトを更新 
update draft api DRAFT_API using content from @file_name

DRAFT_API の値は、 apiname または apiname:version もしくはドラフトAPIのIDである。

update draft api with name APINAME and version VERSION and using content from @file_name
create draft api using @filename and gateway type datapower-api-gateway
 
/update_draft_api api_name:DRAFT_API input_file: @file_name
/update_draft_api api_name:APINAME version:VERSION input_file: @file_name

APIドラフトをダウンロードする

download draft API プロンプトは、 API Connect インスタンスからドラフトAPIをダウンロードする。 この操作には、ドラフトAPI名（バージョン番号の有無にかかわらず）、またはドラフトAPI IDを入力として必要とする。

表 5. パラメータ
パラメーター タイプ 必須 説明
api_name ストリング はい ダウンロードが必要なドラフトAPIの識別子。 この識別子は、API名、 api_name:version、またはドラフトAPIのIDの形式をとることができる。
version ストリング いいえ ドラフトAPIのバージョン。
format JSON/YAML いいえ 出力ファイルのフォーマット。 デフォルトはJSON。
以下のプロンプトを使用して、ドラフトAPIをダウンロードすることができます。
表 6. APIのドラフトをダウンロードする
アクション プロンプト コマンド
API草案のダウンロード 
download draft api DRAFT_API
download draft api with name APINAME and version VERSION
download draft api DRAFT_API in yaml format

DRAFT_API の値は、 apiname または apiname:version もしくはドラフトAPIのIDである。

 
/download_draft_api api_name:DRAFT_API
/download_draft_api api_name:APINAME version:VERSION
/download_draft_api api_name:APINAME version:VERSION format:yaml

DRAFT_API の値は、 apiname または apiname:version もしくはドラフトAPIのIDである。

ドラフトAPIの検証

validate draft api プロンプトは、既存のドラフトまたはファイルアップロードからの API ドラフトの検証を行う。 操作はユーザーの確認なしに直ちに実行され、検証結果が返される。
表 7. パラメータ
パラメーター タイプ 必須 説明
api_name ストリング api_name 、または input_file 。 どちらも設定されていない場合、操作は失敗する。 両方が提供されている場合は、 api_name が優先される。 検証するドラフトAPIの名前を指定する。 この名前は、API名、 api_name:version、またはドラフトAPIのIDの形式で指定できる。
version ストリング いいえ ドラフトAPIのバージョン。
input_file ストリング api_name API定義のドラフトを含むファイル。 ファイルはJSONまたはYAML形式で、Swagger、 OpenAPI,、または API Connect 定義が含まれている必要があります。
catalog ストリング いいえ 検証するカタログの名前またはID。
gateway_service_names ストリング いいえ カタログまたはゲートウェイとの照合時に検証に使用するゲートウェイ・サービス名のカンマ区切りリスト。
ドラフトAPIの検証には、以下のプロンプトを使用できます。
表 8。 APIのドラフトを検証する
アクション プロンプト コマンド
ドラフトAPIの検証 
validate api DRAFT_API
validate api with name APINAME and version VERSION
validate api @file_name
validate api DRAFT_API in catalog CATALOG_NAME
validate api DRAFT_API in catalog CATALOG_NAME and gateway service GATEWAY_SERVICE_NAMES
validate api @file_name in catalog CATALOG_NAME
validate api @file_name in catalog CATALOG_NAME and gateway service GATEWAY_SERVICE_NAMES

注： DRAFT_API の値には、 apiname または apiname:version もしくはドラフトAPIのIDを指定することができる。

 
/validate_api api_name:DRAFT_API
/validate_api api_name:APINAME version:VERSION
/validate_api input_file:@file_name 
/validate_api api_name:DRAFT_API catalog:CATALOG_NAME
/validate_api api_name:DRAFT_API catalog:CATALOG_NAME gateway_service_names:GATEWAY_SERVICE_NAMES
/validate_api input_file:@file_name catalog:CATALOG_NAME
/validate_api input_file:@file_name catalog:catalog_name gateway_service_names:GATEWAY_SERVICE_NAMES

注： DRAFT_API の値には、 apiname または apiname:version もしくはドラフトAPIのIDを指定することができる。

APIの公開

publish api 、プロンプトは API Connect インスタンスにAPIをパブリッシュする。 APIを公開するには、以下の方法がある：

  • 既存のドラフトAPIの名前を提供する
  • API を表す OpenAPI 仕様ファイルのアップロード
注： 実行前にユーザーの確認が必要です。
表 9。 パラメータ
パラメーター タイプ 必須 説明
api_name ストリング api_file 。 公開するAPIのドラフト名。
api_file ストリング オプション OpenAPI 指定を含むファイルへのパス。 api_name 。 ファイルはJSONまたはYAML形式で、Swaggerまたは OpenAPI 標準に準拠している必要があります。
product_file ストリング オプション APIに関連付けられた製品定義を含むファイルへのパス。 提供されない場合、ラッパー製品は発行時に自動生成されます。
gateway_names ストリング オプション APIを公開するゲートウェイ・サービス名のカンマ区切りリスト。 指定しない場合、APIはターゲット・カタログに設定されているすべての関連ゲートウェイ・サービスに公開される。
catalog ストリング オプション APIが公開されているカタログの名前またはID。

指定がない場合、デフォルトで "sandbox" 。
APIを公開するには、以下のプロンプトを使用できます。
表 10。 APIを公開する
アクション プロンプト コマンド
API の公開
  • 名前でAPIを公開する（デフォルトカタログ：sandbox）
    publish api sample
  • APIを特定のカタログに名前を付けて公開する
    publish api sample to catalog test
  • 特定のゲートウェイと特定のカタログに、名前を指定してAPIを公開する。
    publish api sample using gateway gw-service to catalog test
  • OpenAPI の仕様ファイルから特定のカタログにAPIを発行する
    publish api @sample-api.yaml to catalog test
  • 製品ファイルを含む OpenAPI 仕様ファイルから、特定のカタログに API を発行する
    publish api @sample-api.yaml with product @product.yaml to catalog test
  • 名前でAPIを公開する（デフォルトカタログ：sandbox）
    /publish_api name:sample
  • APIを特定のカタログ（例えばtest）に名前付きで公開する
    /publish_api name:sample catalog:test
  • 特定のゲートウェイと特定のカタログに、名前を指定してAPIを公開する。
    /publish_api name:sample gateway_names:gw-service catalog:test
  • OpenAPI の仕様ファイルから特定のカタログにAPIを発行する
    /publish_api api_file: @sample-api.yaml catalog:test
  • 製品ファイルを含む OpenAPI 仕様ファイルから、特定のカタログに API を発行する
    /publish_api api_file: @sample-api.yaml product_file: @product.yaml catalog:test

ドラフトAPIの削除

delete draft api プロンプトは、 API Connect インスタンスからドラフトAPIを削除する。 この操作には、ドラフトAPI名（バージョン番号の有無にかかわらず）、またはドラフトAPI IDを入力として必要とする。

表 11。 パラメータ
パラメーター タイプ 必須 説明
api_name ストリング はい 削除するドラフトAPIの識別子。 この識別子は、API名、 api_name:version 、またはドラフトAPIのIDの形をとることができる。
version ストリング いいえ ドラフトAPIのバージョン。
下書きAPIを削除するには、以下のプロンプトを使用する。
表 12。 下書き削除 API
アクション プロンプト コマンド
ドラフトAPIの削除 
delete draft api DRAFT_API

DRAFT_API の値は、 apiname または apiname:version もしくはドラフトAPIのIDである。

delete draft api with name APINAME and version VERSION
 
/delete_draft_api api_name:DRAFT_API
/delete_draft_api api_name:APINAME version:VERSION

APIにセキュリティを追加する

add security to api プロンプトは、ドラフトAPIにセキュリティスキームを追加する。 この操作は、既存のドラフトAPIまたはドラフトを表すファイルのいずれかを使用して実行することができます。 指定されたセキュリティスキームが利用可能なセキュリティ定義に追加され、API用に設定される。

動作

  • クライアントシークレットセキュリティスキームが追加されると、対応するクライアントIDセキュリティスキームも自動的に追加・設定される。

  • デフォルトでは、セキュリティスキームはヘッダーパラメーターとして設定される。

    セキュリティ・スキームをクエリ・パラメー タとして代わりに構成するには、この操作の開始時に use_query_params_for_apikey_security プロパティを true に設定する。

  • この操作を適切な設定で複数回実行することで、ヘッダーとクエリーパラメーターの両方のスタイルを設定できます。
注:
  • この操作を実行する前に、ユーザーの確認が必要です。
  • このリリースでは、 apiKey セキュリティ・スキーム・タイプのみがサポートされています。
  • oauth2 および。 Basic Authentication
表 13. パラメータ
パラメーター タイプ 必須 説明
api_name ストリング はい セキュリティスキームが追加されるドラフトAPIの識別子。 この識別子は、API名、 api_name:version、またはドラフトAPIのIDの形式をとることができる。 api_name 、または input_file 。 両方が指定された場合は、 api_name が優先される。
version ストリング いいえ ドラフトAPIのバージョン。
input_file ストリング api_name API定義のドラフトを含むファイル。 ファイルはJSONまたはYAML形式で、Swagger、 OpenAPI,、または API Connect 定義が含まれている必要があります。
security_type いいえ 設定するセキュリティスキームのタイプ。 apiKey 。
client_id ブール値 いいえ client_id セキュリティスキームを設定するかどうかを示す。 コンフィギュレーションに含めるには true 。
client_secret ブール値 いいえ true に設定すると、 client_id と client_secret の両方のスキームが自動的に追加される。
use_query_params_for_apikey_security ブール値 いいえ APIリクエストのどこでセキュリティスキームを適用するかを決定します。
  • false (デフォルト）：セキュリティはヘッダーパラメータとして設定される。
  • true:セキュリティはクエリーパラメーターとして設定される。
以下のプロンプトを使用して、ドラフト API にセキュリティを追加できます。
表 14. APIのドラフトにセキュリティ機能を追加する
アクション プロンプト プロンプト
ドラフトAPIにセキュリティを追加する 
add security to api DRAFT_API
add security to api with name APINAME and version VERSION
add client id security to api DRAFT_API
add client id security to api with name APINAME and version VERSION
add client secret security to api DRAFT_API
add client secret security to api with name APINAME and version VERSION
add client id security as a query parameter to api DRAFT_API
add client secret security as a query parameter to api DRAFT_API
add security to api in file @filename
add client id security to api in file @filename
add client secret security to api in file @filename
add client id security as a query parameter to api in file @filename
add client secret security as a query parameter to api in file @filename

DRAFT_API の値は、 apiname または apiname:version もしくはドラフトAPIのIDである。

 
/add_security_to_api api_name:APINAME version:VERSION
/add_security_to_api api_name:APINAME version:VERSION client_secret:true
/add_security_to_api api_name:APINAME version:VERSION use_query_params_for_apikey_security:true
/add_security_to_api api_name:APINAME version:VERSION client_secret:true use_query_params_for_apikey_security:true
/add_security_to_api input_file: @filename
/add_security_to_api input_file: @filename client_secret:true
/add_security_to_api input_file: @filename client_secret:true use_query_params_for_apikey_security:true

APIのセキュリティを見直す

review security of api プロンプトは、ドラフトAPIで定義および設定されているセキュリティスキームをレビューする。 この操作は、既存のドラフトAPIまたはドラフトを表すファイルのいずれかを使用して実行することができます。 この操作は自動的に実行され、ユーザーの確認を必要とせずに出力を返す。

表 15. パラメータ
パラメーター タイプ 必須 説明
api_name ストリング はい レビューするAPI案の識別子。 この識別子は、API名、 api_name:version、またはドラフトAPIのIDの形式をとることができる。 api_name 、または input_file 。 両方が指定された場合は、 api_name が優先される。
version ストリング いいえ ドラフトAPIのバージョン。
input_file ストリング api_name API定義のドラフトを含むファイル。 ファイルはJSONまたはYAML形式で、Swagger、 OpenAPI,、または API Connect 定義が含まれている必要があります。
以下のプロンプトを使用して、ドラフトAPIのセキュリティを確認できます。
表 16. APIの草案のセキュリティを確認する
アクション プロンプト コマンド
API草案のセキュリティを見直す 
review security of api DRAFT_API

DRAFT_API の値は、 apiname または apiname:version もしくはドラフトAPIのIDである。

review security of api with name APINAME and version VERSION
review security of api in file @filename
 
/review_security_of_api api_name:DRAFT_API

DRAFT_API の値は、 apiname または apiname:version もしくはドラフトAPIのIDである。

/review_security_of_api api_name:APINAME version:VERSION
/review_security_of_api input_file: @file_name

ドラフトAPIからセキュリティを削除する

remove security scheme from draft api プロンプトは、ドラフトAPIから1つ以上のセキュリティスキームを削除する。 この操作は、既存のドラフトAPIに対して行うことも、ドラフトを表すファイルを使用して行うこともできる。

指定されたセキュリティスキームが存在すれば、以下の場所から削除される：

  • APIのセキュリティ定義
  • APIレベルで設定されたセキュリティスキームのリスト
  • パスまたはメソッドレベルのセキュリティ設定
注： 実行前にユーザーの確認が必要です。
表 17. パラメータ
パラメーター タイプ 必須 説明
api_name ストリング api_name 、または input_file 。 どちらも設定されていない場合、操作は失敗する。 両方が提供されている場合は、 api_name が優先される。 セキュリティスキームが削除されるドラフトAPIの識別子。 この識別子は、API名、 api_name:version、またはドラフトAPIのIDの形式をとることができる。
version ストリング いいえ ドラフトAPIのバージョン。
input_file ストリング api_name API定義のドラフトを含むファイル。 ファイルはJSONまたはYAML形式で、Swagger、 OpenAPI,、または API Connect 定義が含まれている必要があります。
security_scheme ストリング いいえ 草案で定義されている、削除するセキュリティスキームの正確な名前。
remove_all_security_schemes ブール値 いいえ true に設定すると、ドラフトから定義・設定されたすべてのセキュリティスキームを削除する。 このパラメータを true に設定すると、 security_scheme パラメータは無視される。
以下のプロンプトは、ドラフトAPIのセキュリティを解除するために使用できる：
表 18. APIドラフトの保護を解除する
アクション プロンプト コマンド
ドラフトAPIのセキュリティを削除する 
remove security scheme SECURITY_SCHEME_NAME from api DRAFT_API
remove security scheme SECURITY_SCHEME_NAME from api with name APINAME and version VERSION
remove security scheme SECURITY_SCHEME_NAME from file @filename 
remove all security schemes from api DRAFT_API
remove all security schemes from api with name APINAME and version VERSION
remove all security schemes from file @filename

DRAFT_API の値は、 apiname または apiname:version もしくはドラフトAPIのIDである。

注： ドラフトからセキュリティスキームを削除する場合、ドラフトに存在するスキーム名を正確に入力する必要がある。
 
/remove_security_from_api api_name:DRAFT_API security_scheme:SECURITY_SCHEME_NAME
/remove_security_from_api api_name:APINAME version:VERSION security_scheme:SECURITY_SCHEME_NAME
/remove_security_from_api security_scheme:SECURITY_SCHEME_NAME input_file: @filename
/remove_security_from_api api_name:DRAFT_API remove_all_security_schemes: true
/remove_security_from_api api_name:APINAME version:VERSION remove_all_security_schemes: true
/remove_security_from_api remove_all_security_schemes: true input_file: @filename

DRAFT_API の値は、 apiname または apiname:version もしくはドラフトAPIのIDである。