フードの下のオパリティック – .NETとJSONを使用してPiwik Proをオパールに配線した方法

前の投稿では、オパリティクスをどのようにして人間の質問をし、分析の答えを得ることができるかを示しました。今回は、Oauth Tokens、Discovery Docs、Tool Calling、そして公式のSDKを使用せず、代わりに独自の属性ベースのバージョンを構築しなかった小さな迂回など、完全な開発モードに行きます。

明らかに、まず第一に、私は自分のウェブサイトでPiwik Proトラッキングをセットアップする必要がありました。幸いなことに、これは簡単に行われ、誰もができます 無料トライアルにサインアップしてください。それがセットアップの後、それはあなたのレイアウトにいくつかのJSをコピーして貼り付けるという単純な問題です – またはあなたのタグマネージャーにそれを挿入します。これにより、少なくとも基本的な追跡が行われます – あなたができることがたくさんあります（そしてすべきです）。
トライアルをセットアップすると、サンプルデータのセットにもアクセスできます。これは、以前のBlogPostでデモに使用しました。
すべてがセットアップされたので、開発が開始される可能性があります。

ステップ1：Piwik Proからデータを取得する（涙のないOAuth）

Piwik Proは、クリーンOAuth2を公開します クライアントの資格情報 流れ。 APIクライアントを作成し、トークンとクライアント/秘密をExchange/Secretを作成し、「実行」APIのようなエンドポイントを呼び出して、必要なデータを正確に取得します。 ここでそれについてすべて読むことができます。

clientIDとclientSecretを取得するには、基本的にプロファイルのAPIキーの一部にアクセスして、新しいキーを作成します。
今、それらを手にして、私はAPIを呼び出す準備ができていました。

ハンドローリングカールリクエストは約3分間楽しかったです。だから私は小さなものを始めました .NET SDK auth +「queryを実行する」、「リストの目標」など、いくつかの一般的な呼び出しをラップします。目標：怖いJSONを快適なC＃メソッドに変えます。幸いなことに、分析のレポートデータの多くは、メインの実行クエリメソッドを使用して取得できます。基本的には、1つ以上のディメンションと、タイムスコープと一緒に戻って必要なメトリックを提供します。

かなりまともなドキュメントがあります。PiwikProの開発者ポータルは堅実で、正確なトークンとクエリの形状を示しています。
これがあなたの方法です クエリを実行します、そしてここに本当にあります メトリックと寸法の有用なリスト 使用できます。

これで、_any_クエリを実行することは少し抽象的であり、LLMのために簡単にするために、最も人気のあるページ、キーメトリックなどの最も典型的なクエリのためにLLMに優しい方法のコレクションを作成しました。私は現在、約22人の整っていると思いますが、成長し続けています。

ステップ2：LLMにボタンを押してもらいます（別名ツール呼び出し）

フレンドリーな方法を用意して、私はローカルLLMS（QWEN、DEEPSEEK）をテストしました ツール呼び出し。
サイドノート：1年前にAzure OpenaiのAPIでの不幸な経験の後、数件のテストコールが1万ドルの使用請求書を作成しました。問題の事実 – まともなGPUを持っているなら、セットアップするのは本当に簡単です オラマ そして、独自のローカルAI -llmを実行します。これは、開発とテストに最適です。

すべてのLLMがOpalと同じ高度なメソッドの署名をサポートしているわけではないので、私は彼らのために少し単純化したラッパーを作りました – 基本的には、リターンデータを使用してLLMにテキスト文字列を返すようにしました（LLMはテキストを理解し、そこから構造化されたデータを抽出するのに非常に優れているからです）。一方、Opalは構造化されたデータをバックバックしたいだけです。
ローカルLLMに対するデバッグとテストの利点は、ブレークポイントを簡単にセットアップして通話を介して自分の方法をデバッグできることでした。

ここでは、それがどのように見えるかを見ることができます – そして、Qwenはその思考プロセスを共有するのに十分なほど親切でした。

したがって、基本的にLLMは提供された関数の説明を読み取り、驚くほど適切な方法を選択しました。次の目的地： オパール、Modelsに配線ツールを使用するためのOptimizelyのAIプラットフォーム。

Opalはaを使用します ディスカバリードキュメント– 関数、説明、およびパラメータースキーマのJSONリスト。 Opalがそのドキュメントを見たとき、それはあなたのツールが何をすることができ、いつそれを呼び出すかを知っています。

ただし、Discoveryドキュメントとツール/関数の両方は、Opalがそれらに到達できるようにするために公開Webサイトにある必要があります。そして、それはライブデバッグが少し難しくなる可能性があることを意味します…

ステップ3：「なぜ公式のオパールツールSDKではないのですか？」 （私は試した。）

Optimizelyを提供します Opal Tools SDK .netの場合 それはツールを自動登録し、あなたのために発見を発することができます。それはきちんと進化していますが、私の場合、私はバンプにヒットし、ルーティングと認証に非常に具体的な形状が必要でした。問題と戦うのではなく、私は単にAIコーディングエージェントの信頼できる軍隊に、超軽量の代替品を足場にするように頼んだだけです。 属性駆動型APIコントローラー これにより、スタートアップでDiscovery Docが生成されます。

（最初のツールを構築する場合は、最初にSDKを試してください。ボイラープレートを大幅に削減します。ただし、奇妙なルーティングやカスタムポリシーが必要な場合は、自分で操縦することが速くなります。）

とにかく – Opalを使用するために、MVC Webアプリをプロジェクトに追加し、以前に準備したツールをラップする多くのアクションを備えたToolScontrollerを追加しました。
次に、Opal Discoveryドキュメントを生成できるように、アクションとそれらのパラメーターの両方にカスタム属性を追加しました。 「GetmostPopularurs」などの簡単な方法を見てみると、発見署名は次のようになります。

{
  "functions": [
    {
      "name": "GetMostPopularUrls",
      "description": "Lookup the most visited URLs on the website.",
      "parameters": [
        {
          "name": "DateFrom",
          "type": "string",
          "description": "Start date in ISO (YYYY-MM-DD) or relative range: last_7_days, last_30_days, last_90_days, this_month, last_month, this_year, last_year, yesterday, today. Leave null for default.",
          "required": false
        },
        {
          "name": "DateTo",
          "type": "string",
          "description": "End date in ISO (YYYY-MM-DD). Only used if DateFrom is not a relative range.",
          "required": false
        },
        {
          "name": "Limit",
          "type": "number",
          "description": "Number of URLs to retrieve (default 10).",
          "required": false
        }
      ],
      "endpoint": "/tools/GetMostPopularUrls",
      "http_method": "POST"
    }
  ]
}

これを導入すると、Opalはどのツールが存在するか、それらをどのように呼び出すか、どのパラメーターを期待するかを自動的に認識します。

ステップ4：コード例

コントローラーのアクションとパラメーターがどのように見えるかは次のとおりです。

[OpalTool("GetMostPopularUrls", "Lookup the most visited urls on the website")]
[HttpPost("tools/GetMostPopularUrls")]
public async Task> GetMostPopularUrls(GetMostPopularUrlsParameters parameters)
{
    return await _piwikTools.GetMostPopularUrlsAsync(
        dateFrom: parameters.DateFrom ?? GetDefaultDateFrom(),
        dateTo: parameters.DateTo ?? GetDefaultDateTo(),
        limit: parameters.Limit);
}

public class GetMostPopularUrlsParameters
{
    public const string DateFromDescription =
        "Start date in ISO (YYYY-MM-DD) or relative range: last_7_days, last_30_days, last_90_days, this_month, last_month, this_year, last_year, yesterday, today";
    public const string DateToDescription =
        "End date in ISO (YYYY-MM-DD). Only used if DateFrom is not a relative range.";

    [OpalParameter(DateFromDescription, required: false)]
    public string? DateFrom { get; set; }

    [OpalParameter(DateToDescription, required: false)]
    public string? DateTo { get; set; }

    [OpalParameter("The number of urls to retrieve", required: false)]
    public int Limit { get; set; } = 10;
}

ステップ5：オパールでの登録

コードの準備ができたら、公開ウェブサイトに公開してから、Opalにログインしてツールプロバイダーを登録する時が来ました。

基本的に、Opalにツールを登録して、名前を提供し、Public URLをDiscovery JSONドキュメントに登録できます。必要に応じて、Opalが実行するすべてのコールでHTTPヘッダーに渡されるベアラートークンを提供できます。この方法では、他のアカウントと一緒に結び付けることができます。私のPOCのために、私は簡単な方法を取り、デモデータへのハードコードされたアクセスだけでした。

Opalにアクセスできるが、ツールメニューが表示されない場合、カスタムツールを登録する機能はまだ利用できない可能性があります。でもすぐに来ると確信しています:-)

ステップ6：ループにAIを使用して構築します

私はこれをすべて手作業で行いませんでした：

• Github Copilot →新しいエンドポイント +ディスカバリーエントリ用のPRSを作成しました。
• chatgpt →Sanity-Checked JSONと説明。
• ローカルLLMS →オパールに配線する前にツール呼び出しをテストするのを助けました。

結果：開発が速く、ボイラープレートが少なく、間違いが少なくなります。

ステップ7：アーキテクチャフロー

ピースがどのように合うかは次のとおりです。

まとめ

それが、オパリティクスがボンネットの下でどのように機能するかです：

• Piwik ProにアクセスするOAuth
• 小さな.NET SDK
• ディスカバリードキュメントを生成する属性ベースのコントローラー
• LLMSに分析ツールを自動的に呼び出すためにそのドキュメントを消費するOpal

最終結果：できる分析 話してください、ダッシュボードの代わりに、掘り下げる必要があります。

いつものように、私は本当にやりたいことの長いTODOリストを残しています。このプロジェクトを改善するために、私はここで何かを成し遂げて皆さんと共有できるかどうかを見ています。
また、このプロジェクトは、あなたが提供できるツールに関するいくつかのクレイジーなアイデアを引き起こしました – 時間があればそれらを少し試します。