ビジネス用語集とエントリ リンクのインポート エラーのトラブルシューティング

Knowledge Catalog（旧 Dataplex Universal Catalog）を使用すると、ビジネス用語集とエントリリンクを一括でインポートおよびエクスポートして、ビジネス用語を大規模に管理できます。インポート ユーティリティ スクリプトまたはエクスポート ユーティリティ スクリプトを実行すると、エントリリンクの欠落、空の用語集のエクスポート、無効な用語集またはスプレッドシートの URL、インポート ジョブの中断、スクリプト ネットワーク タイムアウトなどの一般的な問題を診断して解決できます。詳細については、用語集とエントリリンクのインポートとエクスポートについてをご覧ください。

このドキュメントで説明されていない問題の解決にサポートが必要な場合は、Cloud カスタマーケアをご覧ください。

Knowledge Catalog で欠落しているエントリリンクを修正する

エントリリンク エクスポート ユーティリティを実行して、Knowledge Catalog から Google スプレッドシートにエントリリンクをエクスポートすると、生成された Google スプレッドシートに一部のエントリリンク（関連付け）がありません。

この問題は、次の条件により、エクスポート ユーティリティがエントリリンクを自動的にスキップした場合に発生します。

  • 権限が不十分（リソースが削除されている）: リンクに関連付けられているソースエントリまたはターゲット エントリを表示するために必要な IAM 権限がありません。

  • 無効なエントリリンク タイプ: エントリリンクで、サポートされていないか、認識されない関係タイプが使用されています。有効な型は definition、related、synonym に限定されます。

  • 不完全なエントリ参照: エントリ メタデータに必要なスキーマ フィールドがないため、検証チェックでリソースがスキップされます。

この問題を解決するには、次の点を確認してください。

  • 権限を確認する: 欠落しているエントリリンクを表示する権限があることを確認します。スクリプトを実行するプリンシパルに必要なロールが付与されていることを確認します。

  • 実行ログを調べる: ターミナルまたはスクリプトのログで、Skipping redacted entrylink を含む警告を確認します。ログには、スキップされたエントリリンクの特定のリソース ID と、省略された理由が出力されます。

  • リンクスキーマの有効性を確認する: 以前にこれらのリンクをプログラムで変更した場合は、プロパティがスキーマの要件を満たしていることを確認します。

用語集に用語が見つからないエラー

用語集を Google スプレッドシートにエクスポートすると、ビジネス用語集に有効な用語が含まれているにもかかわらず、実行が失敗するか、No terms found in the glossary というメッセージとともに空の結果が返されます。

この問題は、スクリプトが指定された用語集を見つけられない場合や、そのコンテンツを取得するために必要なアクセス権がない場合に発生します。一般的には次のような原因が考えられます。

  • 用語集の URL が正しくない: 実行パラメータで構成された用語集の URL が正しくないか、スペルミスがあります。
  • IAM 権限が不十分: スクリプトを実行している認証済みのサービス アカウントまたはユーザー認証情報に、ターゲット用語集内の用語を表示または一覧表示する権限がありません。
  • 用語集 ID の不一致: スクリプト コマンドで指定された用語集 ID が、Knowledge Catalog の実際の用語集リソース ID と一致しません。

この問題を解決するには、構成と権限を確認します。

  • 用語集 ID を確認する: Google Cloud コンソールで、Knowledge Catalog の [用語集] ページに移動し、用語集を選択して、リソース ID がユーティリティ スクリプトに渡す ID と一致していることを確認します。

  • IAM 権限を確認する: 認証された認証情報（サービス アカウントまたは権限を借用したユーザー アカウント）に必要なロールが付与されていることを確認します。

  • 用語集の URL 構造を検証する: スクリプトに直接リソースパスまたは URL を渡す場合は、次の正しい Knowledge Catalog リソース形式に従っていることを確認します。

    projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID

Knowledge Catalog にエントリが見つからないという警告

エントリリンクのインポート オペレーション中に、スクリプトが一時停止し、次のような警告が表示されます。

Found X entries not found in Knowledge Catalog. EntryLinks associated with
these entries will be skipped. Continue with import? [y/N]:

この問題は、Google スプレッドシートに、Knowledge Catalog に存在しないデータアセットまたは用語集の用語を参照するエントリリンクが含まれている場合に発生します。

この問題は、次のいずれかの方法で解決できます。

  • 部分インポートを続行するには、プロンプトで「y」と入力します。このユーティリティは、有効なエントリリンクをすべてインポートし、欠落しているリソースを参照するリンクのみをスキップします。

  • キャンセルして不足しているリソースを修正するには、「n」と入力して実行をキャンセルします。ソース ドキュメントのエントリ ID が、ナレッジ カタログのリソース名と完全に一致していることを確認します。不足しているリソースや入力ミスを修正してから、インポート スクリプトを再度実行します。

Knowledge Catalog のインポート ジョブが失敗する問題をトラブルシューティングする

インポート ジョブが中断された場合や、実行中に失敗した場合でも、プロセス全体を再開したり、ソースの Google スプレッドシートを変更したりする必要はありません。

このユーティリティは、Cloud Storage ステージング バケットのアーカイブ フォルダを使用して、正常にインポートされたバッチを追跡します。

ジョブを再開する手順は次のとおりです。

  1. インポート ユーティリティを再実行します。ユーティリティが前回の実行状態を検出すると、次のプロンプトが表示されます。

    Found X existing file(s) in archive folder from a previous incomplete import
Continue using existing files? [y/N]:

  2. 「y」と入力します。ユーティリティは、正常にインポートされたバッチをスキップし、残りのファイルのみを処理します。

実行中のスクリプト タイムアウトまたは SSL エラー

インポート ユーティリティ スクリプトまたはエクスポート ユーティリティ スクリプトの実行中に、実行が停止、タイムアウト、またはターミナルで SSL エラーが返されます。

この問題は、次のネットワークレベルのエラーが原因で発生します。

  • 企業プロキシまたはファイアウォールのインターセプト: セキュリティ プロキシまたはファイアウォールが HTTPS トラフィックをインターセプトして検査しているため、SSL 証明書が無効になっています。
  • 有効な VPN 制限: VPN 構成により、特定の Google Cloud API または Google スプレッドシートのエンドポイントへのアウトバウンド トラフィックが制限されています。
  • ローカル ネットワークの不安定さ: インターネット接続が一時的に切断され、セッションが中断されました。

これらのネットワークの問題を解決するには、次の手順を試してください。

  • ネットワーク接続が安定していることを確認します。

  • プロキシとファイアウォールの設定を調べる

  • VPN 構成を確認します。

  • 組み込みの再試行を利用する: ユーティリティ スクリプトには、一時的なネットワーク障害に対する再試行ロジックが組み込まれています。ネットワークの切断が一時的なものである場合は、スクリプトが再試行を完了するまで待ってから、実行を再開します。

「スプレッドシートの URL が無効です」というエラー

インポート ユーティリティまたはエクスポート ユーティリティを実行しようとすると、コマンドライン インターフェースから Invalid spreadsheet URL エラーが返され、実行が停止します。

この問題は、スクリプトが指定された Google スプレッドシートのリンクを解析できない場合や、ファイルの表示権限がない場合に発生します。一般的には次のような原因が考えられます。

  • 不正な形式の URL: URL が標準の Google スプレッドシートのパス形式と一致しません。
  • スプレッドシート ID がありません: パスに、特定のシートを指す一意の英数字 ID がありません。
  • アクセス制限: 認証済みのサービス アカウントにシートの表示または編集の権限がないため、ユーティリティがリンクを検証できません。

この問題を解決するには、スプレッドシートのリンクとアクセス設定を確認します。

  • URL プレフィックスを検証する: ユーティリティに渡すスプレッドシートの URL が、次の標準の Google スプレッドシートのパスで始まっていることを確認します。 https://docs.google.com/spreadsheets/

  • スプレッドシート ID を確認する: URL にシートの一意の ID が含まれていることを確認します。有効な URL は、次の構造に従っている必要があります。 https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit

  • アクセス権限を確認する: ブラウザで Google スプレッドシートを開き、[共有] をクリックして、サービス アカウントのメールアドレスが編集者として追加されていることを確認します。

無効な用語集 URL エラーを解決する

用語集のインポート ユーティリティまたはエクスポート ユーティリティを実行しようとすると、コマンドライン インターフェースから Invalid glossary URL エラーが返され、実行が停止します。パラメータに無効な用語集 URL がないことを確認してください。

この問題は、スクリプトが指定された Knowledge Catalog の用語集リソースパスを解析できない場合、またはリソースを表示する権限がない場合に発生します。一般的には次のような原因が考えられます。

  • リソースパスの形式が正しくない: リソースパスが標準の Knowledge Catalog 用語集パスの形式と一致しません。
  • ID が正しくない: パスに、正しくないプロジェクト ID、リージョンのロケーション、または用語集 ID が含まれています。
  • アクセス制限またはリソースの欠落: 用語集が存在しないか、認証されたサービス アカウントに、用語集にアクセスするために必要な IAM 権限がありません。

この問題を解決するには、用語集のリソースパスと認証情報を確認します。

  • リソースパスの構造を検証する: ユーティリティに渡す用語集のパスが、次の標準の Knowledge Catalog 形式と一致していることを確認します。 projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID

  • パス内の ID を確認する: 正しいプロジェクト ID、ロケーション、用語集 ID を使用します。

  • リソースの存在とアクセスを確認する: 指定された ID の用語集が存在し、認証されたサービス アカウントに必要な IAM ロールが付与されていることを確認します。

実行ログを表示する

インポート ユーティリティとエクスポート ユーティリティは、実行時に詳細な実行ログを生成します。インポート ジョブが失敗した場合は、ログで特定のエラーを確認します。これらのログは、転送プロセスの監査、スキップされたエントリや形式に関する警告の特定に役立ちます。

  • ログの場所: インポート ユーティリティとエクスポート ユーティリティは、ローカル実行パスの logs/ ディレクトリにログファイルを書き込みます。
  • ログ形式: 各ログファイルにはタイムスタンプが付加されているため、特定の実行のログを特定できます。