# parametri personalizzati
<a name="dd-detect-custom-metrics"></a>

Con i parametri personalizzati AWS IoT Device Defender puoi definire e monitorare parametri specifici per il tuo parco istanze o caso d'uso, ad esempio il numero di dispositivi collegati ai gateway Wi-Fi, i livelli di carica per le batterie o il numero di cicli di alimentazione per le prese intelligenti. I comportamenti dei parametri personalizzati sono definiti nei profili di sicurezza, che specificano i comportamenti previsti per un gruppo di dispositivi (un gruppo di oggetti) o per tutti i dispositivi. È possibile monitorare i comportamenti impostando allarmi che puoi utilizzare per rilevare e rispondere a problemi specifici dei dispositivi.

**Topics**
+ [Come utilizzare i parametri personalizzati nella console](#dd-detect-custom-metrics-how-to-console)
+ [Come utilizzare i parametri personalizzati da CLI](#dd-detect-custom-metrics-how-to-cli)
+ [Parametri personalizzati dell'interfaccia a riga di comando](#dd-detect-custom-metrics-cli-commands)
+ [API di parametri personalizzati](#dd-detect-custom-metrics-apis)

## Come utilizzare i parametri personalizzati nella console
<a name="dd-detect-custom-metrics-how-to-console"></a>

**Topics**
+ [AWS IoT Device Defender Agent SDK (Python)](#dd-detect-custom-metrics-device-agent)
+ [Creare un parametro personalizzato e aggiungilo a un profilo di sicurezza](#dd-detect-console-create)
+ [Visualizza dettagli personalizzati dei parametri](#dd-detect-console-read)
+ [Per creare un parametro personalizzato](#dd-detect-console-edit)
+ [Eliminare un parametro personalizzato](#dd-detect-console-delete)

### AWS IoT Device Defender Agent SDK (Python)
<a name="dd-detect-custom-metrics-device-agent"></a>

Per iniziare, scarica l’agente di esempio AWS IoT Device Defender Agent SDK (Python). L'agente raccoglie i parametri e pubblica i report. Dopo la pubblicazione dei parametri sul dispositivo, è possibile visualizzare i parametri raccolti e determinare le soglie per l'impostazione degli allarmi. Le istruzioni per la configurazione dell'agente dispositivo sono disponibili su [AWS IoT Readme Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst). Per ulteriori informazioni, consulta [AWS IoT Device Defender SDK Agent (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python).

### Creare un parametro personalizzato e aggiungilo a un profilo di sicurezza
<a name="dd-detect-console-create"></a>

La procedura seguente mostra come creare un gruppo di parametri tramite la console.

1. Nell’[AWS IoT console](https://console.aws.amazon.com/iot), nel pannello di navigazione, espandi **Defend (Protezione)**, poi **Detect (Rileva)**, e **Metrics (Parametri)**.

1. Sulla pagina **Custom metrics (Parametri personalizzati)**, scegli **Create (Crea)**.

1. Nella pagina **Create custom metric (Crea parametri personalizzati)**, esegui le seguenti operazioni.

   1. In **Name (Nome)** immetti un nome per il parametro personalizzato. Non è possibile modificare questo nome dopo aver creato il parametro personalizzato.

   1. In **Display name (Visualizza nome) (opzionale)** puoi immettere un nome facilmente identificabile per il parametro personalizzato. Non deve essere univoco e può essere modificato dopo la creazione.

   1. In **Type (Tipo)**, scegli il tipo di parametro che desideri monitorare. I tipi di parametri includono **string-list**, **ip-address-list**, **number-list** e **number**. Il tipo di parametro non può essere modificato dopo la creazione.
**Nota**  
ML Detect consente solo il tipo **numero**.

   1. In **Tag** è possibile selezionare i tag da associare alla risorsa.

   Al termine, scegli **Confirm (Conferma)**.

1. Dopo aver creato il parametro personalizzato, appare la pagina **Custom metrics (Parametri personalizzati)** in cui è possibile visualizzare il parametro personalizzato appena creato.

1. A questo punto, aggiungi il parametro personalizzato a un profilo di sicurezza. Nell’[AWS IoT console](https://console.aws.amazon.com/iot), nel pannello di navigazione, espandi **Defend (Protezione)**, poi scegli **Detect (Rileva)**, e seleziona **Security profiles (Profili di sicurezza)**.

1. Scegli il profilo di sicurezza a cui desideri aggiungere il parametro personalizzato.

1. Scegli **Actions (Operazioni)**, **Edit (Modifica)**.

1. Scegli **Additional Metrics to retain (Parametri aggiuntivi da conservare)**, quindi scegli il parametro personalizzato. Scegli **Next (Successivo)** nelle seguenti schermate fino a raggiungere la pagina **Confirm (Conferma)**. Seleziona **Save (Salva)** e **Continue (Continua)**. Dopo aver aggiunto correttamente il parametro personalizzato, viene visualizzata la pagina dei dettagli del profilo di sicurezza.
**Nota**  
Le statistiche di percentile non sono disponibili per i parametri quando uno qualsiasi dei valori dei parametri è un numero negativo.

### Visualizza dettagli personalizzati dei parametri
<a name="dd-detect-console-read"></a>

La procedura seguente mostra come visualizzare i dettagli di un parametro personalizzato nella console.

1. Nell’[AWS IoT console](https://console.aws.amazon.com/iot), nel pannello di navigazione, espandi **Defend (Protezione)**, poi scegli **Detect (Rileva)**, e **Metrics (Parametri)**.

1. Seleziona **Metric name (Nome parametro)** del parametro personalizzato di cui desideri visualizzare i dettagli.

### Per creare un parametro personalizzato
<a name="dd-detect-console-edit"></a>

La procedura seguente illustra come aggiornare un parametro personalizzato nella console.

1. Nell’[AWS IoT console](https://console.aws.amazon.com/iot), nel pannello di navigazione, espandi **Defend (Protezione)**, poi scegli **Detect (Rileva)**, e **Metrics (Parametri)**.

1. Scegli il pulsante di opzione accanto al parametro personalizzato che desideri aggiornare. Quindi, per **Actions (Operazioni)**, scegli **Edit (Modifica)**.

1. Sulla pagina **Update custom metric (Aggiorna parametro personalizzato)**, è possibile modificare il nome visualizzato e rimuovere o aggiungere tag.

1. Al termine, scegli **Update (Aggiorna)**. La pagina **Custom metric (Parametri personalizzati)**.

### Eliminare un parametro personalizzato
<a name="dd-detect-console-delete"></a>

La procedura seguente mostra come eliminare un parametro personalizzato tramite la console.

1. Innanzitutto, rimuovi il parametro personalizzato da qualsiasi profilo di sicurezza a cui fa riferimento. È possibile visualizzare quali profili di sicurezza contengono il parametro personalizzato nella pagina dei dettagli dei parametri personalizzati. Nell’[AWS IoT console](https://console.aws.amazon.com/iot), nel pannello di navigazione, espandi **Defend (Protezione)**, poi scegli **Detect (Rileva)**, e **Metrics (Parametri)**.

1. Scegli il parametro personalizzato che desideri rimuovere. Rimuovi il parametro personalizzato da qualsiasi profilo di sicurezza elencato in **Security Profiles (Profili di sicurezza)** nella pagina dei dettagli dei parametri personalizzati.

1. Nell’[AWS IoT console](https://console.aws.amazon.com/iot), nel pannello di navigazione, espandi **Defend (Protezione)**, poi scegli **Detect (Rileva)**, e **Metrics (Parametri)**.

1. Scegli il pulsante di opzione accanto al parametro personalizzato da eliminare. Per **Actions (Operazioni)**, scegli **Delete (Elimina)**.

1. Sul messaggio **Are you sure you want to delete custom metric? (Sei sicuro di voler cancellare il parametro personalizzato?)**, scegli **Delete custom metric (Elimina parametro personalizzato)**.
**avvertimento**  
Dopo aver eliminato un parametro personalizzato, si perdono tutti i dati associati al parametro. Questa operazione non può essere annullata.

## Come utilizzare i parametri personalizzati da CLI
<a name="dd-detect-custom-metrics-how-to-cli"></a>

**Topics**
+ [AWS IoT Device Defender Agent SDK (Python)](#dd-detec-custom-metrics-cli-sdk)
+ [Creare un parametro personalizzato e aggiungerlo a un profilo di sicurezza](#dd-detect-custom-cli-create)
+ [Visualizzare dettagli personalizzati dei parametri](#dd-detect-custom-cli-read)
+ [Aggiornare un parametro personalizzato](#dd-detect-custom-cli-edit)
+ [Eliminare un parametro personalizzato](#dd-detect-custom-cli-delete)

### AWS IoT Device Defender Agent SDK (Python)
<a name="dd-detec-custom-metrics-cli-sdk"></a>

Per iniziare, scarica l’agente di esempio AWS IoT Device Defender Agent SDK (Python). L'agente raccoglie i parametri e pubblica i report. Dopo la pubblicazione dei parametri sul dispositivo, è possibile visualizzare i parametri raccolti e determinare le soglie per l'impostazione degli allarmi. Le istruzioni per la configurazione dell'agente dispositivo sono disponibili su [Readme AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst). Per ulteriori informazioni, consulta [AWS IoT Device Defender SDK Agent (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python).

### Creare un parametro personalizzato e aggiungerlo a un profilo di sicurezza
<a name="dd-detect-custom-cli-create"></a>

La procedura seguente mostra come creare un parametro personalizzato e aggiungerlo a un profilo di sicurezza dall'interfaccia della riga di comando.

1. Utilizzo dell'`[create-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/create-custom-metric.html)` per creare il parametro personalizzato. Nell'esempio seguente viene creato un parametro personalizzato che misura la percentuale della batteria.

   ```
   aws iot create-custom-metric \
       --metric-name "{{batteryPercentage}}" \
       --metric-type "{{number}}" \
       --display-name "{{Remaining battery percentage.}}" \
       --region {{us-east-1}}
       --client-request-token "{{02ccb92b-33e8-4dfa-a0c1-35b181ed26b0}}" \
   ```

   Output:

   ```
   {
       "metricName": "{{batteryPercentage}}",
       "metricArn": "arn:aws:iot:{{us-east-1}}:{{1234564789012}}:custommetric/{{batteryPercentage}}"
   }
   ```

1. Dopo aver creato il parametro personalizzato, è possibile aggiungerlo a un profilo esistente utilizzando `[update-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profile.html)`, oppure creare un nuovo profilo di sicurezza per aggiungere il parametro personalizzato tramite `[create-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/create-security-profile.html)`. In questo modo, viene creato un nuovo profilo di sicurezza chiamato {{batteryUsage}} per aggiungere il nuovo parametro personalizzato {{batteryPercentage}}. Aggiungiamo anche un parametro Rules Detect chiamato {{cellularBandwidth}}.

   ```
   aws iot create-security-profile \
       --security-profile-name {{batteryUsage}} \
       --security-profile-description "{{Shows how much battery is left in percentile.}}"  \
       --behaviors "[{\"name\":\"great-than-75\",\"metric\":\"{{batteryPercentage}}\",\"criteria\":{\"comparisonOperator\":\"greater-than\",\"value\":{\"number\":75},\"consecutiveDatapointsToAlarm\":5,\"consecutiveDatapointsToClear\":1}},{\"name\":\"{{cellularBandwidth}}\",\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}]" \
       --region {{us-east-1}}
   ```

   Output:

   ```
   {
       "securityProfileArn": "{{arn:aws:iot:us-east-1:1234564789012:securityprofile/batteryUsage}}",
       "securityProfileName": "{{batteryUsage}}"
   }
   ```

**Nota**  
Le statistiche di percentile non sono disponibili per i parametri quando uno qualsiasi dei valori dei parametri è un numero negativo.

### Visualizzare dettagli personalizzati dei parametri
<a name="dd-detect-custom-cli-read"></a>

La procedura seguente mostra come visualizzare i dettagli per un parametro personalizzato dall'interfaccia della riga di comando.
+ Utilizzo del comando `[list-custom-metrics](https://docs.aws.amazon.com/cli/latest/reference/iot/list-custom-metrics.html)` per visualizzare tutti i parametri personalizzati.

  ```
  aws iot list-custom-metrics \
      --region {{us-east-1}}
  ```

  L'output di questo comando è simile al seguente.

  ```
  {
      "metricNames": [
          "{{batteryPercentage}}"
      ]
  }
  ```

### Aggiornare un parametro personalizzato
<a name="dd-detect-custom-cli-edit"></a>

La procedura seguente mostra come aggiornare un parametro personalizzato dall'interfaccia a riga di comando.
+ Utilizzo del comando `[update-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/update-custom-metric.html)` per aggiornare un parametro personalizzato. Nell'esempio seguente viene aggiornato il `display-name`.

  ```
  aws iot update-custom-metric \
      --metric-name {{batteryPercentage}} \
      --display-name '{{remaining battery percentage on device}}' \
      --region {{us-east-1}}
  ```

  L'output di questo comando è simile al seguente.

  ```
  {
      "metricName": "{{batteryPercentage}}",
      "metricArn": "arn:aws:iot:{{us-east-1}}:{{1234564789012}}:custommetric/{{batteryPercentage}}",
      "metricType": "number",
      "displayName": "{{remaining battery percentage on device}}",
      "creationDate": "2020-11-17T23:01:35.110000-08:00",
      "lastModifiedDate": "2020-11-17T23:02:12.879000-08:00"
  }
  ```

### Eliminare un parametro personalizzato
<a name="dd-detect-custom-cli-delete"></a>

La procedura seguente mostra come eliminare un parametro personalizzato dall'interfaccia a riga di comando.

1. Per eliminare un parametro personalizzato, scollegalo prima da tutti i profili di sicurezza a cui è collegato. Utilizzo del comando `[list-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/list-security-profiles.html)` per visualizzare i profili di sicurezza con un determinato parametro personalizzato.

1. Per rimuovere un parametro personalizzato da un profilo di sicurezza, utilizza il comando `[update-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profiles.html)`. Immetti tutte le informazioni che desideri conservare, ma escludi il parametro personalizzato.

   ```
   aws iot update-security-profile \
     --security-profile-name {{batteryUsage}} \
     --behaviors "[{\"name\":\"{{cellularBandwidth}}\",\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}]"
   ```

   L'output di questo comando è simile al seguente.

   ```
   {
     "behaviors": [{\"name\":\"{{cellularBandwidth}}\",\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}],
     "securityProfileName": "{{batteryUsage}}",
     "lastModifiedDate": 2020-11-17T23:02:12.879000-09:00,
     "securityProfileDescription": "{{Shows how much battery is left in percentile.}}",
     "version": 2,
     "securityProfileArn": "{{arn:aws:iot:us-east-1:1234564789012:securityprofile/batteryUsage}}",  
     "creationDate": 2020-11-17T23:02:12.879000-09:00
   }
   ```

1. Dopo che il parametro personalizzato è stato scollegato, utilizza il comando `[delete-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-custom-metric.html)` per eliminare il parametro personalizzato.

   ```
   aws iot delete-custom-metric  \
     --metric-name {{batteryPercentage}} \
     --region {{us-east-1}}
   ```

   L'output di questo comando è simile al seguente

   ```
   HTTP 200
   ```

## Parametri personalizzati dell'interfaccia a riga di comando
<a name="dd-detect-custom-metrics-cli-commands"></a>

Puoi utilizzare i comandi CLI seguenti per creare e gestire parametri personalizzati.
+ [create-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/create-custom-metric.html)
+ [describe-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-custom-metric.html)
+ [list-custom-metrics](https://docs.aws.amazon.com/cli/latest/reference/iot/list-custom-metrics.html)
+ [update-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/update-custom-metric.html)
+ [delete-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-custom-metric.html)
+ [list-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/list-security-profiles.html)

## API di parametri personalizzati
<a name="dd-detect-custom-metrics-apis"></a>

Per creare e gestire parametri personalizzati, è possibile utilizzare le seguenti API.
+ [CreateCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCustomMetric.html)
+ [DescribeCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeCustomMetric.html)
+ [ListCustomMetrics](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCustomMetrics.html)
+ [UpdateCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCustomMetric.html)
+ [DeleteCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCustomMetric.html)
+ [ListSecurityProfiles](https://docs.aws.amazon.com/iot/latest/apireference/API_ListSecurityProfiles.html)