アノテーションAPI
UIからノートを作成できるだけでなく、注釈プラグインは、注釈を表示、追加、変更できるウェブAPIも提供している。もしあなたがプログラマーなら、このAPIを使って面白いアプリを作ることができる。
まだ作られていないアプリ：
以下は、Annotations APIを使用するアプリのアイデアのリストです。これらのアプリはまだ作成されていませんが、もし存在するのであれば、私たちはそれが大好きです。
- 変更が加えられたり、新しいブログ記事が書かれたりするたびに、Matomoのデータに自動的に注釈を付けるWordPressプラグイン。
- あなたのgithubアカウントを監視し、コミットや新しいリリースのたびにMatomoのデータに注釈を付けるアプリです。
- 購読者リストにメールを送信するたびに、Matomoのデータに注釈を付けるアプリです。
アノテーションAPIはMatomoのAPIの一部です。APIがどのように動作するかについては、こちらをご覧ください。すでにAPIの使い方を知っていて、それを使ってアノテーションを操作する方法を知りたいなら、このまま読み進めて下さい。
APIを使ってアノテーションを表示する
既存のアノテーションを照会するには、2つのAPIメソッドを使用できます：
- Annotations.get– 単一の注釈を取得します。パラメーターは以下。
- idSite:注釈が属するウェブサイトのID。
- idNote:注釈のID。
- Annotations.getAll– 複数の注釈を取得する。パラメーターは以下。
- idSite:注釈を検索するウェブサイトのID。複数のIDを指定する場合は、カンマ区切りで指定する。
- date:注釈が付けられた日付。periodが’range’に設定されている場合は日付範囲。
- period:使用する期間。デフォルトでは’day’が使用される。他の値 (例えば ‘week’、’month’、’year’、’range’) を指定すると、その期間内のアノテーションが返されます。
- lastN(オプション) 指定された場合、最後の N 期間が検索に含まれる。
ただし、アノテーションのカウントだけに興味がある場合は、別のAPIメソッドを使うことができる：
- Annotations.getAnnotationCountForDates– 期間内の注釈とスター付き注釈の数を取得します。パラメーターは以下。
- idSite:注釈をカウントするウェブサイトのID。
- date:注釈が付けられた日付。periodが’range’に設定されている場合は日付範囲。
- period:使用する期間。デフォルトでは’day’が使用される。他の値 (例えば ‘week’、’month’、’year’、’range’) を指定すると、その期間内のアノテーションが返されます。
- lastN(オプション) 指定された場合、最後の N 期間が検索に含まれる。
APIを使ってアノテーションを追加・変更する
アノテーションを作成、変更、削除するには、以下のAPIメソッドを使用します：
- Annotations.add – ウェブサイトと日付の新しい注釈を追加する。パラメーターは以下。
- idSite:注釈が追加されるウェブサイトのID。
- date:注釈を付ける日付。
- note:注釈のテキスト。
- starred: （オプ シ ョ ナル）1か0のどちらか。1の場合、 こ の注釈は星印で始ま る。0または指定がない場合は使用しない。
- Annotations.save– 既存の注釈を変更する。パラメーターは以下。
- idSite:注釈が属するウェブサイトのID。
- idNote:注釈のID。
- date（オプ シ ョ ナル） 設定すると 、 既存の注釈の日付が、 与え る日付に変更 さ れます。
- note（オプ シ ョ ナル） 設定すると、 既存の注釈テキス ト は、 与え るテキス ト に変更 さ れます。
- starred:（オプ シ ョ ナル）指定する と 、 注釈は、 こ のパ ラ メ タ の値に基づいて、 星印付きか星印なしかのいずれかにな り ます。1 の場合はスター付き、0 の場合はスターなしとなる。
- Annotations.delete– 既存の注釈を削除します。パラメーターは以下。
- idSite:注釈が属するウェブサイトのID。
- idNote:注釈のID。
MatomoのBulk Request機能を使ってアプリを高速化する
作成しようとしているアプリが大量のアノテーションを作成または変更する場合は、一括APIリクエストの送信を検討するとよいだろう。一度に1つのHTTPリクエストを送信して数十個（またはそれ以上）のアノテーションを作成すると、一括リクエストを発行するよりもはるかに遅くなります。詳細はこちらをお読みください。