はじめに
API Connectでは、開発用のコマンドとしてToolkitを提供しており、API ManagerなどのGUIで登録した情報を取得することができます。この記事では、特にカタログ内に存在するユーザーデータをToolkitでコピーする方法を紹介します(この検証は、v10.0.5.0の環境で実施しています)。以下のようなイメージとなります。
API ConnectではManagementサーバーのデータ移行において構成Backup/Restore方法が提供されていますが、この方法はその環境の復旧を目的としているため、移行先が同じシステム構成である前提があったり、特定のデータだけの移行には使えないという制約があります。今回ご紹介する方法は、異なる環境に一部のデータを移行したいという場合に参考になるかと思います。
1. 移行元の情報取得(test-org)
Toolkitで情報を取得するため、プロバイダー組織にアクセス権のあるユーザーでAPI Managerにログインします。
# 環境変数設定
APIM_USER='test-user'
APIM_PASSWORD='********'
APIM_SERVER='https://example.com'
APIM_PROVIDER_REALM=provider/default-idp-2
ORG_SOURCE='test-org'
# ログインコマンド
$ ./apic login --username ${APIM_USER} --password ${APIM_PASSWORD} --server ${APIM_SERVER} --realm ${APIM_PROVIDER_REALM}
example.com に正常にログインしました
1.1 公開済み製品・APIの取得
$ ./apic products:clone -o ${ORG_SOURCE} --server ${APIM_SERVER} --scope catalog --catalog test-catalog
test-api:1.0.0 test-api_1.0.0.yaml
test-product:1.0.0 test-product_1.0.0.yaml
1.2 開発者組織所有者情報の取得
$ ./apic users:get -o ${ORG_SOURCE} --server ${APIM_SERVER} --user-registry test-catalog-catalog test-dev
test-dev test-dev.yaml https://example.com/api/user-registries/2865de4d-0f29-493f-8242-f89639a64b67/af2c6589-39f3-4725-9a00-32366aa6a9b9/users/b6703958-3347-41a5-9b99-51377f17aea4
$ cat test-dev.yaml
type: 'user'
api_version: '2.0.0'
id: 'b6703958-3347-41a5-9b99-51377f17aea4'
name: 'test-dev'
title: 'test-dev'
state: 'enabled'
identity_provider: 'test-catalog-idp'
username: 'test-dev'
email: 'test-dev@jp.ibm.com'
first_name: 'test'
last_name: 'test'
created_at: '2022-12-19T07:46:35.000Z'
updated_at: '2022-12-19T07:46:35.000Z'
org_url: 'https://example.com/api/orgs/2865de4d-0f29-493f-8242-f89639a64b67'
user_registry_url: 'https://example.com/api/user-registries/2865de4d-0f29-493f-8242-f89639a64b67/af2c6589-39f3-4725-9a00-32366aa6a9b9'
url: 'https://example.com/api/user-registries/2865de4d-0f29-493f-8242-f89639a64b67/af2c6589-39f3-4725-9a00-32366aa6a9b9/users/b6703958-3347-41a5-9b99-51377f17aea4'
1.3 開発者組織情報の取得
以下の方法で所有者の設定情報を取得できますが機密情報であるパスワードは取得できませんので、移行する場合には、別途、控えておく必要があります。
$ ./apic consumer-orgs:get -o ${ORG_SOURCE} --server ${APIM_SERVER} --catalog test-catalog test-dev-org
test-dev-org test-dev-org.yaml https://example.com/api/consumer-orgs/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968
$ cat test-dev-org.yaml
type: 'consumer_org'
api_version: '2.0.0'
id: '71ba6bfa-fedb-4370-8904-8631e99f9968'
name: 'test-dev-org'
title: 'test-dev-org'
state: 'enabled'
owner_url: 'https://example.com/api/user-registries/2865de4d-0f29-493f-8242-f89639a64b67/af2c6589-39f3-4725-9a00-32366aa6a9b9/users/b6703958-3347-41a5-9b99-51377f17aea4'
created_at: '2022-12-19T07:46:35.000Z'
updated_at: '2022-12-19T07:46:35.000Z'
org_url: 'https://example.com/api/orgs/2865de4d-0f29-493f-8242-f89639a64b67'
catalog_url: 'https://example.com/api/catalogs/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f'
url: 'https://example.com/api/consumer-orgs/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968'
1.4 アプリケーション情報の取得
$ ./apic apps:get -o ${ORG_SOURCE} --server ${APIM_SERVER} --catalog test-catalog --consumer-org test-dev-org test-app
test-app test-app.yaml https://example.com/api/apps/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968/743832da-2fe6-483b-9233-c78e862627bf
$ cat test-app.yaml
type: 'app'
api_version: '2.0.0'
id: '743832da-2fe6-483b-9233-c78e862627bf'
name: 'test-app'
title: 'test-app'
state: 'enabled'
lifecycle_state: 'production'
app_credential_urls:
- 'https://example.com/api/apps/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968/743832da-2fe6-483b-9233-c78e862627bf/credentials/75023a26-71d2-4d4c-830a-c75102d2dc12'
created_at: '2022-12-19T07:50:09.000Z'
updated_at: '2022-12-19T07:50:09.000Z'
org_url: 'https://example.com/api/orgs/2865de4d-0f29-493f-8242-f89639a64b67'
catalog_url: 'https://example.com/api/catalogs/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f'
consumer_org_url: 'https://example.com/api/consumer-orgs/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968'
url: 'https://example.com/api/apps/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968/743832da-2fe6-483b-9233-c78e862627bf'
1.5 クレデンシャル情報の取得
API ManagerやPortalでアプリケーションを登録すると、その名前と紐づいたクレデンシャル情報(Credential-for-xxx.yaml)が作成され、Client ID、Client Secretが払い出されます。しかし、以下の情報の通りToolkitでも機密情報であるClient Secretの値は取得できませんので、移行する場合は、アプリケーション作成時に表示される情報を控えておく必要があります。
$ ./apic credentials:get -o ${ORG_SOURCE} --server ${APIM_SERVER} --app test-app --catalog test-catalog --consumer-org test-dev-org Credential-for-test-app
Credential-for-test-app Credential-for-test-app.yaml https://example.com/api/apps/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968/743832da-2fe6-483b-9233-c78e862627bf/credentials/75023a26-71d2-4d4c-830a-c75102d2dc12
$ cat Credential-for-test-app.yaml
type: 'credential'
api_version: '2.0.0'
id: '75023a26-71d2-4d4c-830a-c75102d2dc12'
name: 'Credential-for-test-app'
title: 'Credential for test-app'
summary: 'Credential for test-app'
client_id: '844a3673bc853d1acc23d7041b73f796'
client_secret_hashed: 'D+8HnuNQQltVQpCZc9lutl79jgOcgNWn9+3hLwclI3I='
created_at: '2022-12-19T07:50:09.000Z'
updated_at: '2022-12-19T07:50:09.000Z'
org_url: 'https://example.com/api/orgs/2865de4d-0f29-493f-8242-f89639a64b67'
catalog_url: 'https://example.com/api/catalogs/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f'
consumer_org_url: 'https://example.com/api/consumer-orgs/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968'
app_url: 'https://example.com/api/apps/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968/743832da-2fe6-483b-9233-c78e862627bf'
url: 'https://example.com/api/apps/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968/743832da-2fe6-483b-9233-c78e862627bf/credentials/75023a26-71d2-4d4c-830a-c75102d2dc12'
1.6 サブスクリプション情報の取得
$ ./apic subscriptions:get -o ${ORG_SOURCE} --server ${APIM_SERVER} --app test-app --catalog test-catalog --consumer-org test-dev-org test-product-1.0.0-default-plan
test-product-1.0.0-default-plan test-product-1.0.0-default-plan.yaml https://example.com/api/apps/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968/743832da-2fe6-483b-9233-c78e862627bf/subscriptions/84906c48-e69d-4db9-a44f-80f325f75c39
$ cat test-product-1.0.0-default-plan.yaml
type: 'subscription'
api_version: '2.0.0'
id: '84906c48-e69d-4db9-a44f-80f325f75c39'
name: 'test-product-1.0.0-default-plan'
title: 'test-product 1.0.0 default-plan'
state: 'enabled'
product_url: 'https://example.com/api/catalogs/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/products/3b1452bc-2a52-4e2e-a088-32219798c9f8'
plan: 'default-plan'
plan_title: 'デフォルトのプラン'
task_urls: []
created_at: '2022-12-19T07:50:37.000Z'
updated_at: '2022-12-19T07:50:37.000Z'
org_url: 'https://example.com/api/orgs/2865de4d-0f29-493f-8242-f89639a64b67'
catalog_url: 'https://example.com/api/catalogs/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f'
consumer_org_url: 'https://example.com/api/consumer-orgs/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968'
app_url: 'https://example.com/api/apps/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968/743832da-2fe6-483b-9233-c78e862627bf'
url: 'https://example.com/api/apps/2865de4d-0f29-493f-8242-f89639a64b67/b109cd53-9b18-4c19-97eb-840adcfe222f/71ba6bfa-fedb-4370-8904-8631e99f9968/743832da-2fe6-483b-9233-c78e862627bf/subscriptions/84906c48-e69d-4db9-a44f-80f325f75c39'
2. 移行先へ情報登録(test-org-copy)
Toolkitで情報を登録するため、移行先のプロバイダー組織にアクセス権のあるユーザーでAPI Managerにログインします。
# 環境変数設定
APIM_USER='test-user-copy'
APIM_PASSWORD='********'
APIM_SERVER='https://example.com'
APIM_PROVIDER_REALM=provider/default-idp-2
ORG_TARGET='test-org-copy'
# ログインコマンド
$ ./apic login --username ${APIM_USER} --password ${APIM_PASSWORD} --server ${APIM_SERVER} --realm ${APIM_PROVIDER_REALM}
example.com に正常にログインしました
2.1 公開済み製品・APIの登録
$ ./apic products:publish -o ${ORG_TARGET} --server ${APIM_SERVER} --scope catalog --catalog test-catalog test-product_1.0.0.yaml
test-product:1.0.0 [state: published] https://example.com/api/catalogs/08f70fe0-44cd-4e40-8692-f2c9b248f7c3/847478fc-2079-4703-b9c7-adee0f756a70/products/258edcc0-f1d0-4631-bd7d-53434fa0f819
2.2 開発者組織所有者情報の登録
移行先では、IDやURLが変わるため、定義ファイルには必要最低限の設定を入れていきます。この考え方は、これ以降の定義の登録で共通の処理となります。
IDやURLが残っていても問題はありませんが無視され、新しいID/URLが設定されます。1.2と2.2の結果を比べるとID/URLが変わっていることが確認できます。
# 定義ファイルには以下を残す(パスワードは追加)
$ cat test-dev.yaml
name: 'test-dev'
title: 'test-dev'
state: 'enabled'
identity_provider: 'test-catalog-idp'
username: 'test-dev'
password: '********'
email: 'test-dev@jp.ibm.com'
first_name: 'test'
last_name: 'test'
$ ./apic users:create -o ${ORG_TARGET} --server ${APIM_SERVER} --user-registry test-catalog-catalog test-dev.yaml
test-dev [state: enabled] https://example.com/api/user-registries/08f70fe0-44cd-4e40-8692-f2c9b248f7c3/b32b7c5e-2ad9-4a6b-81f8-e59b42c9bdd7/users/caf85ec3-a47a-4986-b51f-1fd0f77b5c61
2.3 開発者組織情報の登録
この組織の登録には、所有者(owner_url)の事前登録が必要です。
$ cat test-dev-org.yaml
name: 'test-dev-org'
title: 'test-dev-org'
state: 'enabled'
owner_url: 'https://example.com/api/user-registries/08f70fe0-44cd-4e40-8692-f2c9b248f7c3/b32b7c5e-2ad9-4a6b-81f8-e59b42c9bdd7/users/caf85ec3-a47a-4986-b51f-1fd0f77b5c61'
$ ./apic consumer-orgs:create -o ${ORG_TARGET} --server ${APIM_SERVER} --catalog test-catalog test-dev-org.yaml
test-dev-org [state: enabled] https://example.com/api/consumer-orgs/08f70fe0-44cd-4e40-8692-f2c9b248f7c3/847478fc-2079-4703-b9c7-adee0f756a70/93debd0f-086f-48d1-b6ef-c81511158b47
2.4 アプリケーション情報の登録
この情報の登録には、開発者組織の登録(--consumer-org)が必要です。
$ cat test-app.yaml
name: 'test-app'
title: 'test-app'
state: 'enabled'
lifecycle_state: 'production'
$ ./apic apps:create -o ${ORG_TARGET} --server ${APIM_SERVER} --catalog test-catalog --consumer-org test-dev-org test-app.yaml
test-app [state: enabled] https://example.com/api/apps/08f70fe0-44cd-4e40-8692-f2c9b248f7c3/847478fc-2079-4703-b9c7-adee0f756a70/93debd0f-086f-48d1-b6ef-c81511158b47/24370311-9270-4779-915e-a8b6c9e926db
2.5 クレデンシャル情報の更新
この情報の更新には、アプリケーションの登録(--app)が必要です。アプリケーション登録時に新規にClient ID、Client Secretが自動生成されています。そのため、このコマンドで、もとの情報に更新しています。
または、2.4の実行の際に、アプリケーションの定義ファイル(test-app.yaml)に同じようにclient_id、client_secretを設定することで反映することも可能です。
$ cat Credential-for-test-app.yaml
name: 'Credential-for-test-app'
title: 'Credential for test-app'
summary: 'Credential for test-app'
client_id: '844a3673bc853d1acc23d7041b73f796'
client_secret: '5a10e9af72c7b0e33e39b083e38a5e7d'
$ ./apic credentials:update -o ${ORG_TARGET} --server ${APIM_SERVER} --app test-app --catalog test-catalog --consumer-org test-dev-org Credential-for-test-app Credential-for-test-app.yaml
Credential-for-test-app https://example.com/api/apps/08f70fe0-44cd-4e40-8692-f2c9b248f7c3/847478fc-2079-4703-b9c7-adee0f756a70/93debd0f-086f-48d1-b6ef-c81511158b47/24370311-9270-4779-915e-a8b6c9e926db/credentials/e1549190-e639-41df-b87f-ebcb121af1c1
2.6 サブスクリプション情報の登録
この情報の登録には、製品(product_url)とアプリケーションの登録(--app)が必要です。
$ cat test-product-1.0.0-default-plan.yaml
name: 'test-product-1.0.0-default-plan'
title: 'test-product 1.0.0 default-plan'
state: 'enabled'
product_url: 'https://example.com/api/catalogs/08f70fe0-44cd-4e40-8692-f2c9b248f7c3/847478fc-2079-4703-b9c7-adee0f756a70/products/258edcc0-f1d0-4631-bd7d-53434fa0f819'
plan: 'default-plan'
plan_title: 'デフォルトのプラン'
task_urls: []
$ ./apic subscriptions:create -o ${ORG_TARGET} --server ${APIM_SERVER} --app test-app --catalog test-catalog --consumer-org test-dev-org test-product-1.0.0-default-plan.yaml
test-product-1.0.0-default-plan [state: enabled] https://example.com/api/apps/08f70fe0-44cd-4e40-8692-f2c9b248f7c3/847478fc-2079-4703-b9c7-adee0f756a70/93debd0f-086f-48d1-b6ef-c81511158b47/24370311-9270-4779-915e-a8b6c9e926db/subscriptions/fed0a709-1f38-495b-9dbf-2f5181c00154
3. 結果確認
以上でAPI呼び出しに必要となる最低限のユーザーデータのコピーが完了しました。
コピー先の環境でも同様のAPIやアプリケーションが使用できますので、以下のように呼び出すことが可能です。
$ curl -ki --request GET \
--url https://gateway.example.com/test-org-copy/test-catalog/v1/test \
--header 'x-ibm-client-id: 844a3673bc853d1acc23d7041b73f796' \
--header 'x-ibm-client-secret: 5a10e9af72c7b0e33e39b083e38a5e7d'
HTTP/1.1 200 OK
Connection: Keep-Alive
Transfer-Encoding: chunked
User-Agent: curl/7.83.1
Accept: */*
x-ibm-client-secret: 5a10e9af72c7b0e33e39b083e38a5e7d
X-RateLimit-Limit: name=default,100;
X-RateLimit-Remaining: name=default,99;
Date: Mon, 19 Dec 2022 08:42:21 GMT
Content-Type: text/plain
ok
以上です。