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

このドキュメントでは、Knowledge Catalog（旧称 Dataplex Universal Catalog）で用語集とエントリリンクをインポートおよびエクスポートする際に発生する一般的な問題とエラーを解決する方法について説明します。

このページで説明されていない問題の解決についてサポートが必要な場合は、 Google Cloud サポートにお問い合わせください。

エクスポートされた Google スプレッドシートにエントリリンクがない

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

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

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

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

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

この問題を解決するには、次のチェックを行います。

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

用語集を 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 エラーが返され、実行が停止します。

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

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

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

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

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

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

実行ログを表示する

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

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