このガイドでは、用語集とエントリ リンクを インポートおよびエクスポートする際に発生する Knowledge Catalog の問題をトラブルシューティングする方法について説明します。 たとえば、エントリ リンクがない場合、「用語集の URL が無効です」というエラーが表示される場合、インポート ジョブが失敗する場合などです。
このページで説明されていない問題の解決についてサポートが必要な場合は、 Google Cloud サポートにお問い合わせください。
Knowledge Catalog で不足しているエントリ リンクを修正する
この問題は、次の条件により、エクスポート ユーティリティがエントリ リンクを自動的にスキップする場合に発生します。
権限が不足している（編集されたリソース）: リンクに関連付けられたソース エントリまたはターゲット エントリを表示するために必要な 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 ステージング バケットのアーカイブ フォルダを使用して、正常にインポートされたバッチを追跡します。
ジョブを再開する手順は次のとおりです。
インポート ユーティリティを再実行します。ユーティリティは前回の実行の状態を検出し、次のプロンプトを表示します。
Found X existing file(s) in archive folder from a previous incomplete import Continue using existing files? [y/N]:「
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/ディレクトリに書き込みます。 - ログ形式: 各ログファイルにはタイムスタンプが付加されるため、特定の実行のログを見つけることができます。