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

このガイドは、用語集とエントリ リンクのインポートとエクスポートを行う際に発生する Knowledge Catalog の問題（エントリ リンクの欠落、無効な用語集 URL エラー、インポート ジョブの失敗など）のトラブルシューティングに役立ちます。

このページで説明されていない問題の解決についてサポートが必要な場合は、Google 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 のリソース名と完全に一致していることを確認します。不足しているリソースや誤字脱字を修正してから、インポート スクリプトを再度実行します。

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 の用語集が存在し、認証されたサービス アカウントに必要な IAM ロールが付与されていることを確認します。

実行ログを表示する

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

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