Marketplace で Developer Console アプリケーションをインストールする

Marketplace を使用して、Developer Console アプリケーションをパッケージ化し、Foundry 環境間でインストールします。アプリケーションまたはそのコードリポジトリをパッケージ化できます。

1. アプリケーションのパッケージ化： Developer Console アプリケーションを、そのメタデータおよび OAuth クライアントとともにパッケージ化します。本番およびシングルトン製品を使用してデプロイ済みの Web サイトを配布する場合に推奨される方法です。Web サイトアセットが存在しない場合でも、この方法で OAuth クライアントを配布できます。詳細は、Developer Console アプリケーションをパッケージ化してインストールするを参照してください。
2. ソースコードのパッケージ化： Developer Console アプリケーションを含めずに、Web サイトのコードリポジトリをパッケージ化します。テンプレート化されたアプリケーションや、宛先環境で別の Developer Console アプリケーションを作成する場合に推奨される方法です。詳細は、Developer Console に関連付けられたソースコードをパッケージ化してテンプレート化するを参照してください。

既存の Web サイトがない状態で OAuth クライアントをセットアップする場合は、アプリケーションとそのソースコードの両方をパッケージ化すると役立つことがあります。この場合、インストール後にアプリケーションコードを変更し、インストールされた OAuth クライアントを使用する Web サイトを公開したいことがあります。このワークフローは、本番アプリケーションでは一般的ではありません。インストールされたアプリケーションは常に最新の Web サイトアセット（存在する場合）と一致するため、ソースコードは実質的に無視されるからです。

Developer Console アプリケーションのパッケージ化とインストール

パッケージ化済みのアプリケーションには、次のものが含まれます。

• Web サイトアセット： Web サイトアセットが生成されたアプリケーションの静的ファイルとコンテンツセキュリティポリシー（Web サイトホスティングを参照）。DevOps はデフォルトで、Web サイトアセットの最新のデプロイ済みバージョンをパッケージ化します。ソースにデプロイ済みアセットが存在しない場合は、未デプロイの最新アセットバージョンを使用します。
• アプリケーションメタデータ： 名前、説明、設定。
• OAuth クライアント： クライアントの種類、グラントタイプ、リダイレクト URL。
• リソース制限： オントロジー SDK とプラットフォーム SDK のリソース。

DevOps でアプリケーションをパッケージ化する

Foundry DevOps で、Developer Console アプリケーションを製品の出力として追加します。Developer Console アプリケーションには、2種類の依存関係があります。

1. アプリケーションの制限に含まれるオントロジーリソース（およびその依存関係）と Compass プロジェクト。
2. インストールの一環として定義する必要があるパラメーター入力。これには、Web サイトホスティングのサブドメインとセキュリティマーキングが含まれます。

アプリケーションをインストールする

Marketplace からアプリケーションをインストールすると、Developer Console リソースが自動的に作成され、OAuth が設定されます。製品のインストールについては、詳しくはこちらをご覧ください。場合によっては、インストール中に手動で操作する必要があります。

• ブートストラップモードでは、同じオントロジー内での競合を避けるために、Marketplace がオントロジーのAPI名を自動的に書き換える場合があります。たとえば、オブジェクトタイプ API_NAME=Truck をインストールする際に、インストール先のオントロジーにオブジェクトタイプ API_NAME=Truck がすでに存在する場合、Marketplace はインストールするオブジェクトタイプの名前を Truck_1 に変更することがあります。これにより、API名でオブジェクトを参照するインストール済みアプリケーションが動作しなくなる可能性があります。アプリケーションとともにオントロジーリソースをインストールする場合は、インストール中に常にソースのオントロジーのAPI名をインストールを選択します。これにより、プレフィックスの追加や変更を行わずに元のAPI名が保持され、アプリケーションコードが引き続き動作します。

• パッケージ化済みのアプリケーションがサブドメインホスティングを使用する場合、Marketplace でのインストールの一環として新しいサブドメインが定義されます。通常、これには追加の承認が必要で、多くの場合、情報セキュリティ責任者による承認が求められます。インストール後にサブドメインを承認するには、Developer Console の［Web サイトホスティング］ページに移動します。この承認が得られるまで、Web サイトにはアクセスできません。

Compass で管理される権限

Compass で管理されるユーザー権限を使用すると、Marketplace は、ほかのインストールリソースとともに、指定した場所に Developer Console アプリケーションを作成します。

以前にデプロイしたアプリケーションを Compass で管理される権限に移行する場合は、次の点に留意してください。

• Marketplace 製品のパッケージ化済みアプリケーションを移行しても、以前にデプロイしたインストールは自動的に移行されません。
• 権限のドキュメントに記載された移行手順を使用して、インストールごとに個別に移行する必要があります。
• インストールがロックされている場合、アプリケーションを対象の場所に移動する前に、ロック解除を求めるダイアログが表示されることがあります。

アプリケーションをアップグレードする

Marketplace 製品の一部としてインストール済みアプリケーションを更新するには、次の手順を実行します。

1. ソース環境でアプリケーションを更新します。
2. Web サイトアセットを更新する場合は、まず Developer Console でデプロイします。DevOps は、最も新しいデプロイ済み Web サイトアセットをパッケージ化します。
3. Foundry DevOps で新しい製品バージョンを作成します。

アプリケーションパラメーターの再マッピング

ビルド済みの Web サイトアセットを持つアプリケーションでは、Marketplace がインストール中にアプリケーションパラメーターを自動的にマッピングします。次の値が、対象環境の対応する値に置き換えられます。

• Foundry URL
• OAuth クライアントID
• OAuth リダイレクト URL
• オントロジー RID
• オントロジーのAPI名

自動マッピングが機能するには、アプリケーションは、パッケージ化されたアプリケーションコード自体ではなく、index.html のメタタグからこれらの値を読み取る必要があります。@osdk/create-app ↗ v2.1.3 以降、または Foundry の VS Code ワークスペースで作成されたアプリケーションは、デフォルトでこのように設定されています。

上記のアプリケーションパラメーターとは異なり、オブジェクトタイプやアクションタイプなどのオントロジーリソースのAPI名は、インストール中に自動的に再マッピングされません。環境間でAPI名の一貫性を管理する方法については、API名の変更に対処するを参照してください。

既存のアプリケーションを更新する

@osdk/create-app ↗ v2.1.3 より前に作成されたアプリケーションでは、設定の自動置換を有効にするためにコードを変更する必要があります。index.html に次のメタタグを追加します。

Copied!
1
2
3
4
<meta name="osdk-clientId" content="%VITE_FOUNDRY_CLIENT_ID%" />
<meta name="osdk-redirectUrl" content="%VITE_FOUNDRY_REDIRECT_URL%" />
<meta name="osdk-foundryUrl" content="%VITE_FOUNDRY_API_URL%" />
<meta name="osdk-ontologyRid" content="%VITE_FOUNDRY_ONTOLOGY_RID%" />

次に、これらのメタタグから読み取るようにクライアントの初期化を更新します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import { createClient, type Client } from "@osdk/client";
import { createPublicOauthClient, type PublicOauthClient } from "@osdk/oauth";

function getMetaTagContent(tagName: string): string {
    const elements = document.querySelectorAll(`meta[name="${tagName}"]`);
    const element = elements.item(elements.length - 1);
    const value = element ? element.getAttribute("content") : null;
    if (value == null || value === "") {
        throw new Error(`Meta tag ${tagName} not found or empty`);
    }
    if (value.match(/%.+%/)) {
        throw new Error(
            `Meta tag ${tagName} contains placeholder value. Add ${value.replace(/%/g, "")} to your .env files`,
        );
    }
    return value;
}

const foundryUrl = getMetaTagContent("osdk-foundryUrl");
const clientId = getMetaTagContent("osdk-clientId");
const redirectUrl = getMetaTagContent("osdk-redirectUrl");
const ontologyRid = getMetaTagContent("osdk-ontologyRid");

export const auth: PublicOauthClient = createPublicOauthClient(
    clientId,
    foundryUrl,
    redirectUrl,
);

export const client: Client = createClient(foundryUrl, ontologyRid, auth);

.env ファイルにオントロジー RID を追加します。

VITE_FOUNDRY_ONTOLOGY_RID=<ri.ontology.main.ontology.your-ontology-rid>

カスタム Workshop ウィジェットの統合

カスタム Workshop ウィジェットは、Developer Console アプリケーションと同様にデプロイされます。ウィジェットセットを Marketplace 製品に追加するを参照してください。

制限事項

• 機密クライアントのシークレット： 機密クライアントはパッケージ化できますが、インストール先の環境で新しいシークレットを生成するために手動の操作が必要です。Developer Console で［OAuth と制限］に移動し、シークレットをローテーションを選択すると、新しいシークレットを生成できます。
• スタンドアロン OAuth クライアントは非対応： スタンドアロン OAuth クライアントをパッケージ化して Marketplace でデプロイすることはできません。代わりに制限なしのアプリケーションを使用してください。
• バージョンが固定された関数は非対応： パッケージ化するには、アプリケーションのオントロジー SDK に含まれるすべての関数で最新バージョンを使用する必要があります。関数のバージョンが固定されたアプリケーションは、現在 Marketplace に対応していません。この制限は、今後のリリースで変更される可能性が高いです。

Developer Console に関連付けられたソースコードをパッケージ化およびテンプレート化する

アプリケーションのソースコードは、ほかのコードリポジトリと同様にパッケージ化できます。アプリケーションのパッケージ化とは異なり、オントロジー RID やリダイレクト URL などの設定パラメーターは、ソースコード内では再マッピングされません。つまり、ソースコードをアプリケーションと一緒に配布すると、アプリケーションの Web サイトは宛先環境で正常に動作しますが、ソースコードファイルには元の環境のパラメーターが残ります。

テンプレート化（ベータ版）

ソースコードのみをインストールする場合は、アプリケーションをテンプレート化して、インストール時にパラメーターが自動的に書き換えられるようにできます。通常、ブートストラップモードでは、次の場合にテンプレート化が適しています。

• すべての開発者が、事前設定済みのオントロジー SDK アプリケーションを使ってコードをセットアップする必要があるブートキャンプやワークショップを開催する場合。
• ユーザーが作業を始めるための例を提供する場合。
• すべての React プロジェクトに UI 標準を適用する場合。
• 共通のオントロジーリソースを使用する React テンプレートを提供する場合。

アプリケーションをテンプレート化するには、次の手順を実行します。

1. インストール時に書き換える必要があるコード内の変数に、ハンドルバーを追加します（例：{{my_variable}}）。
2. DevOps で、該当するコードリポジトリを追加し、リポジトリの設定メニューでソースコードのテンプレート化を有効にします。

3. カスタムパラメーターについては、Marketplace がユーザーにパラメーター値の入力を求めるプロンプトを表示し、インストール時に値を解決します。予約済みパラメーターは、インストール時に自動的に置き換えられます。
4. Marketplace からテンプレートをインストールすると、新しいリポジトリと、それにリンクされた Developer Console アプリケーションがユーザー向けに自動的に作成されます。このパッケージをセットアップに使用する場合は、インストール時にセットアップオプションを選択する必要があります。

ハンドルバーパラメーターを使用すると、型チェックによりアプリケーションの CI チェックに失敗します。そのため、CI チェックに合格した後にデプロイされる Web サイトのアセットを、テンプレート化されたコードと一緒にパッケージ化することはできません。

予約済みパラメーター

カスタムパラメーターに加えて、TypeScript のオントロジー SDK アプリケーションには、インストール時にそれぞれの値へ自動的に解決される次の予約済みパラメーターがあります。

予約済みパラメーターには、次の制約があります。

• アプリケーションのパッケージ名に @ を含めたり、末尾に /sdk を付けたりすることはできません。
• インストール後にテンプレートがそのまま動作するには、package.json 内のオントロジー SDK のバージョンを latest または 0.1.0 に設定する必要があります。

API名の変更への対処

オントロジー SDK は、API名でオントロジーリソースを参照します。そのため、インストールされた Developer Console アプリケーション（またはアプリケーションコード）が動作するには、使用するリソースのAPI名がソースと宛先のオントロジーで一致している必要があります。

この動作は、人間が読んで理解するためのものではない RID を使用してリソースを参照し、エンロールメント間でその RID をマッピングする、ほとんどの Foundry アプリケーションとは異なります。たとえば、rid=X のオブジェクトタイプを参照する Workshop アプリケーションは、デプロイ時に rid=y のオブジェクトタイプを参照するように書き換えられることがあります。一方、コンパイル済みのオントロジー SDK アプリケーションアセットと生のオントロジー SDK コードは、人間が読んで理解でき、ソースと宛先のリポジトリで同一であることを意図しています。

リソースのAPI名の一貫性を確保するため、可能な場合は、オントロジーリソースとアプリケーションの両方をパッケージ化してインストールしてください。オントロジーリソースは、Developer Console アプリケーションとともに製品の出力にする必要があります（または、最初の製品とともにデプロイする2件目の製品の出力にします）。これにより、Marketplace はソースと同じAPI名で宛先のオントロジーにリソースを作成し、動作が壊れるのを防ぎます。オントロジーリソースをインストールするときは、ソースのオントロジーのAPI名を常にインストールするを選択して、元の名前を保持します。

API名の重複に対処する方法は、2つのカテゴリーに分かれた4つの方法があります。

オントロジーをアプリケーションとともにパッケージ化する場合： 同じAPI名のオブジェクトタイプが宛先のオントロジーにすでに存在する場合、Marketplace はインストール接頭辞を適用するため、オントロジー SDK コードの動作が壊れるおそれがあります。これを避けるには、完全修飾名または別々のスペースを使用します。

オントロジーをアプリケーションとともにパッケージ化しない場合： 宛先の環境に必要なオントロジーリソースがすでにある場合は、それらを直接参照します。ソースと宛先のオブジェクトタイプが意図的に異なっていても、共通の構造を持つ場合は、インターフェースを使用します。オブジェクトが同一で名前だけが異なる場合は、環境間で一致するようにAPI名を手動で変更します。

完全修飾名

オントロジーをパッケージ化するときに名前の重複を防ぐには、ソース環境でオントロジーリソースを定義するときに完全修飾API名を使用します。完全修飾API名には名前空間の接頭辞が含まれ、オントロジーをまたいでグローバルに一意になります。アプリケーションがオントロジーごとに1回だけデプロイされる、つまりシングルトン製品である限り、完全修飾名によってAPI名の重複が起きないことが保証されます。

Ontology Manager で完全修飾名を設定します。

別々のスペースを使用する

複数の組織にまたがるワークフローや開発ライフサイクルのワークフローでは、別々のスペースを使用することも、API名の重複を解消する方法です。API名の一意性は、スペースレベルでのみ適用されます。各スペースはオントロジーと一対一で対応するため、ユーザーはこれをオントロジーレベルの一意性と考えることができます。

インターフェース

重複するAPI名が、実際には同じインターフェースの2つの実装を表していることがあります。このような場合は、具体的なオブジェクトタイプではなくインターフェースを使用するように、アプリケーションコードを書き換えることを検討してください。

たとえば、ソースのオントロジーでは medicine オブジェクトタイプを使用するアプリケーションがあり、宛先の環境には代わりに vaccine オブジェクトタイプがある場合を考えます。medicine をオブジェクトタイプではなくインターフェースとして表すことで、これを簡素化できます。この場合、medicine インターフェースは Marketplace 製品の一部としてデプロイされ、宛先のオントロジーでは vaccine が medicine を実装します。この方法には、人間が読んで理解できるコード、構築時に明確になる抽象化、宛先の環境での適切なオントロジー上の機密情報区分という利点があります。

つまり、オブジェクトタイプではなくインターフェースを基にアプリケーションを構築すると、アプリケーションコードの可読性が保証され、多くの場合、オブジェクトをマッピングする必要がなくなります。

API名を手動で変更する

ソースと宛先に同一のオブジェクトがあり、API名が異なる場合は、環境間で一致するようにAPI名を手動で編集する必要があります。API名を変更すると、そのリソースを参照するほかのアプリケーションや関数の動作が壊れる可能性があるため、慎重に進めてください。