# Google Search Consoleを連携する

Google Search Consoleのプロパティに、Kafkaiの読み取り権限を付与します。連携すると、実際の検索クエリ、クリック数、表示回数、掲載順位を、AIエージェントからKafkai経由で読み取れるようになります。作業は、Kafkaiの読み取り用アドレス（メールアドレス）をプロパティのユーザーに追加するだけです。パスワードを共有する必要はなく、KafkaiがSearch Consoleの設定を変更することもありません。

## 準備するもの

- 対象サイトのKafkaiプロジェクト
- Search Consoleプロパティの**オーナー**権限。ユーザーを追加できるのはオーナーだけです
- プロジェクトのドメインを対象に含むプロパティ
    - ドメインプロパティ（`hogehoge.jp`）は、ドメインとすべてのサブドメインを対象にします。`blog.hogehoge.jp` のプロジェクトにも対応します。
    - URLプレフィックスプロパティ（`https://www.hogehoge.jp/`）は、ホストが完全に一致するプロジェクトにだけ対応します。
    - フォルダ付きのURLプレフィックスプロパティ（`https://hogehoge.jp/blog/`）は、どのプロジェクトにも対応しません。そのフォルダのデータだけを扱うプロパティのためです。

## 1. Kafkaiでドメインを認証する

Kafkaiアカウントの[ドメインの管理ページ](https://kafkai.com/ja/accounts/domains/)を開きます。ページに表示されたTXTレコードを、そのドメインのDNSに追加します。ドメインのDNSを編集できない場合（ホスティングサービスのサイトなど）は、同じページに表示されたメタタグを、サイトの `<head>` に追加します。どちらかを設置したら、**確認**を選択します。エージェントに「Kafkaiでドメインを認証して」と依頼することもできます。ドメイン認証は無料です。

ドメインを認証するまでは、Kafkaiはそのドメインについて何も返しません。Search Consoleのプロパティがあるかどうかも返しません。詳しくは、ツールリファレンスの[ドメイン認証](https://kafkai.com/ja/docs/tools/#ドメイン認証)をご覧ください。

## 2. Kafkaiの読み取り用アドレスをコピーする

[ドメインの管理ページ](https://kafkai.com/ja/accounts/domains/#connect-search-console)で、Kafkaiの読み取り用アドレスをコピーします。アドレスは、すべてのドメインとすべてのプロジェクトで共通です。このページのスクリーンショットではアドレスの大半を隠しています。画像から入力するのではなく、アカウントの画面からコピーしてください。

## 3. プロパティのユーザー設定を開く

[Google Search Console](https://search.google.com/search-console)で、対象のプロパティを選択します。メニューの**設定** > **ユーザーと権限**を選択します。

<img src="https://kafkai.com/static/images/docs/connect/gsc-01-settings-ja.webp" alt="Search Consoleの設定画面。メニューの設定と、ユーザーと権限の行が枠で囲まれている" width="800" loading="lazy">

## 4. 読み取り用アドレスを「制限付き」で追加する

**ユーザーを追加**を選択します。メールアドレスの欄にKafkaiの読み取り用アドレスを貼り付け、**権限**は**制限付き**を選択します。最後に**追加**を選択します。

**制限付き**は、Search Consoleでいちばん低い権限です。Kafkaiができるのは、データの閲覧だけです。追加すると、ユーザー一覧に読み取り用アドレスが**制限付き**で表示されます。

<img src="https://kafkai.com/static/images/docs/connect/gsc-02-users-and-permissions-ja.webp" alt="Search Consoleのユーザーと権限の一覧。Kafkaiの読み取り用アドレスが枠で囲まれ、権限は制限付きになっている" width="800" loading="lazy">

## 5. データを取得する

KafkaiはSearch Consoleのアカウントを常時監視していません。プロパティを探すのは、データの取得を依頼されたときだけです。エージェントに「KafkaiでプロジェクトのSearch Consoleのデータを更新して」と依頼します。エージェントは `kafkai_update_search_console` を呼び出します。この呼び出しは無料です。

Kafkaiがプロパティを見つけて、履歴を16か月分取り込みます。最初の取得には数分かかります。

あとで新しいデータが必要になったら、同じ依頼をもう一度してください。取得できるのは1日1回です。GoogleがSearch Consoleのデータを公開するのが1日1回のためです。調査の実行（`kafkai_update_keywords`）でもデータを更新し、その日の1回として数えます。調査はクレジットを消費します。Search Consoleだけを更新する場合、調査は必要ありません。

## 連携の状態を確認する

エージェントに「KafkaiのプロジェクトでSearch Consoleは連携できている？」と質問します。エージェントは `kafkai_get_project_summary` の `search_console.status` を確認します。

| ステータス | 意味 |
| --- | --- |
| `not_connected` | 手順が不足しています。不足している手順は `next_step_suggestion` に示されます。 |
| `syncing` | プロパティを見つけ、履歴を取り込んでいる途中です。 |
| `ready` | データを利用できます。 |

ステータスが `ready` になったら、「直近28日間でクリックが減った検索クエリは？」のような質問ができます。このデータを読み取る2つのツールについては、ツールリファレンスの[Search Console](https://kafkai.com/ja/docs/tools/#search-console)をご覧ください。

## ステータスが `not_connected` のままの場合

- **ドメインを認証していない。** [ドメインの管理ページ](https://kafkai.com/ja/accounts/domains/)を開き、**確認**を選択します。TXTレコードを削除した場合は、追加し直すまでデータは読み取れません。
- **アドレスに入力ミスがある。** Search Consoleでユーザーをいったん削除し、ドメインの管理ページからコピーしたアドレスを貼り付け直します。

アドレスを追加したあとに、エージェントが `kafkai_update_search_console` を呼び出したかどうかも確認してください。プロパティの種類がプロジェクトのホストを対象にしているかどうかも、あわせて確認してください。プロパティが見つからなかった場合、Kafkaiが次に探すのは1分後です。続けて呼び出すときは、1分あけてください。

## 権限を取り消す

Kafkaiによる読み取りを停止するには、Search Consoleで**設定** > **ユーザーと権限**を開きます。読み取り用アドレスの行のメニューから**アクセス権を削除**を選択します。削除した時点から、Kafkaiはプロパティを読み取れなくなります。
