本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# PreviewAnomalyDetector API
<a name="anomaly-detection-api"></a>

使用 `PreviewAnomalyDetector`操作建立端點，示範如何在指定期間內，由異常偵測演算法分析指標資料。此端點可協助您在實作之前評估和驗證偵測器的效能。

有效的 HTTP 動詞  
`GET`, `POST`

支援的承載類型  
URL 編碼參數  
適用於 `POST` 的 `application/x-www-form-urlencoded`

支援的參數  
`query=<string>` Prometheus 表達式查詢字串。  
`start=<rfc3339 | unix_timestamp>` 若您正在使用 `query_range` 查詢時間範圍，則開始時間戳記。  
`end=<rfc3339 | unix_timestamp>` 若您正在使用 `query_range` 查詢時間範圍，則結束時間戳記。  
`step=<duration | float>` 查詢解析度步驟寬度 (`duration` 格式或 `float` 秒數)。只有在您正在使用 `query_range` 查詢時間範圍，並在此類查詢必要時才可使用。

## 查詢參數格式
<a name="anomaly-detection-query-formatting"></a>

使用查詢參數中的 RandomCutForest (RCF) 虛擬函數包裝原始 PromQL 表達式。如需詳細資訊，請參閱《*Amazon Managed Service for Prometheus API 參考*》中的 [RandomCutForestConfiguration](https://docs.aws.amazon.com/prometheus/latest/APIReference/API_RandomCutForestConfiguration.html)。

RCF 函數使用此格式：

```
RCF(<query>
[,shingle size
[,sample size
[,ignore near expected from above
[,ignore near expected from below
[,ignore near expected from above ratio
[,ignore near expected from below ratio]]]]])
```

查詢以外的所有參數都是選用的，並在省略時使用預設值。最小語法為：

```
RCF(<query>)
```

您必須使用彙總函數來包裝查詢。若要在省略其他參數時使用特定選用參數，請在函數中保留空白位置：

```
RCF(<query>,,,,,1.0,1.0)
```

此範例只會根據預期值和觀察值之間的比率，設定忽略異常偵測峰值和下降的比率參數。

## API 請求與回應
<a name="anomaly-detection-query-formatting"></a>

成功的呼叫會傳回與 [QueryMetrics API](AMP-APIReference-QueryMetrics.md) 相同的格式。除了原始時間序列之外，API 還會在有足夠的可用範例時傳回這些新的時間序列：
+ `anomaly_detector_preview:lower_band` – PromQL 表達式結果預期值的下限
+ `anomaly_detector_preview:score` – 異常分數介於 0 到 1 之間，其中 1 表示該資料點對異常的高度可信度
+ `anomaly_detector_preview:upper_band` – PromQL 表達式結果預期值的上帶

 **請求範例** 

```
POST /workspaces/workspace-id/anomalydetectors/preview
Content-Type: application/x-www-form-urlencoded

query=RCF%28avg%28vector%28time%28%29%29%29%2C%208%2C%20256%29&start=1735689600&end=1735695000&step=1m
```

 **回應範例** 

```
200 OK
...

{
  "status": "success",
  "data": {
    "result": [
      {
        "metric": {},
        "values": [
          [
            1735689600,
            "1735689600"
          ],
          [
            1735689660,
            "1735689660"
          ],
          .........
        ]
      },
      {
        "metric": {
          "anomaly_detector_preview": "upper_band"
        },
        "values": [
          [
            1735693500,
            "1.7356943E9"
          ],
          [
            1735693560,
            "1.7356945E9"
          ]
          ],
          .........
        ]
      },
      {
        "metric": {
          "anomaly_detector_preview": "lower_band"
        },
        "values": [
          [
            1735693500,
            "1.7356928E9"
          ],
          [
            1735693560,
            "1.7356929E9"
          ],
          ......... 
        ]
      },
      {
        "metric": {
          "anomaly_detector_preview": "score"
        },
        "values": [
          [
            1735693500,
            "0.0"
          ],
          [
            1735695000,
            "0.0"
          ],
          .........
        ]
      }
    ],
    "resultType": "matrix"
  }
}
```