Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Creazione di modelli di attività del worker personalizzati
<a name="a2i-custom-templates"></a>

Gli *elementi Crowd HTML* sono componenti Web che forniscono una serie di widget di attività ed elementi di progettazione che è possibile adattare alla domanda che si desidera porre. Puoi utilizzare questi elementi crowd per creare un modello del worker personalizzato e integrarlo con un flusso di lavoro di revisione umana IA aumentata Amazon (Amazon A2I) per personalizzare la console di lavoro e le istruzioni. 

Per l'elenco di tutti gli elementi crowd HTML disponibili per gli utenti Amazon A2I, consulta [Riferimento per gli elementi Crowd HTML](sms-ui-template-reference.md). Per esempi di modelli, consulta il [AWS GitHubrepository](https://github.com/aws-samples/amazon-a2i-sample-task-uis), che contiene oltre 60 modelli di attività personalizzati di esempio.

## Sviluppo di modelli in locale
<a name="developing-templates-locally"></a>

Quando usi la console per testare come il modello elabora i dati in entrata, puoi verificare l'aspetto dell'HTML del modello e degli elementi personalizzati nel browser aggiungendo il seguente codice all'inizio del file HTML.

```
<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>
```

Questo consente di caricare il codice necessario per eseguire il rendering degli elementi HTML personalizzati. Utilizza questo codice se desideri sviluppare l'aspetto del modello nell'editor preferito anziché nella console.

Questo codice non analizza le variabili. Durante lo sviluppo in locale potrebbe essere necessario sostituirlo con il contenuto di esempio.

## Utilizzo di risorse esterne
<a name="a2i-custom-template-using-external-assets"></a>

I modelli personalizzati IA aumentata Amazon consentono di incorporare script esterni e fogli di stile. Ad esempio, l'intestazione seguente incorpora nel modello personalizzato un foglio di stile `text/css` denominato `stylesheet` presente in `https://www.example.com/my-enhancement-styles.css`.

**Example**  

```
<script src="https://www.example.com/my-enhancment-script.js"></script>
<link rel="stylesheet" type="text/css" href="https://www.example.com/my-enhancement-styles.css">
```

Se si verificano errori, verifica che il server di origine stia inviando il tipo MIME corretto e le intestazioni di codifica con gli asset.

Ad esempio, i tipi MIME e di codifica per gli script remoti sono: `application/javascript;CHARSET=UTF-8`.

I tipi MIME e di codifica MIME per i fogli di stile remoti sono: `text/css;CHARSET=UTF-8`.

## Monitoraggio delle variabili
<a name="a2i-custom-template-step2-UI-vars"></a>

Quando crei un modello personalizzato, devi aggiungervi le variabili per rappresentare le parti di dati che potrebbero cambiare da attività a attività o da worker a worker. Se inizi con uno dei modelli di esempio, accertati di conoscere le variabili già in uso. 

Ad esempio, per un modello personalizzato che integra un ciclo di revisione umana IA aumentata con un'attività di revisione del testo Amazon Textract viene utilizzato `{{ task.input.selectedAiServiceResponse.blocks }}` per i dati di input del valore iniziale. Per IA aumentata Amazon (Amazon A2I) viene utilizzata l'integrazione con Amazon Rekognition. `{{ task.input.selectedAiServiceResponse.moderationLabels }}` Per un tipo di attività personalizzato, è necessario determinare il parametro di input per il tipo di attività. Utilizza `{{ task.input.customInputValuesForStartHumanLoop}}` dove specifichi `customInputValuesForStartHumanLoop`. 

## Esempio di modello personalizzato per Amazon Textract
<a name="a2i-custom-templates-textract-sample"></a>

Tutti i modelli personalizzati iniziano e terminano con gli elementi `<crowd-form> </crowd-form>`. Analogamente agli elementi HTML `<form>` standard, tutto il codice del modulo deve essere racchiuso tra questi elementi. 

Per un'attività di analisi dei documenti Amazon Textract, utilizza l'elemento `<crowd-textract-analyze-document>`. Utilizza gli attributi seguenti: 
+ `src`: specifica l'URL del file immagine da annotare.
+ `initialValue`: imposta i valori iniziali per gli attributi che si trovano nell'interfaccia utente del worker.
+ `blockTypes` (obbligatorio): determina il tipo di analisi che i worker possono eseguire. Al momento è supportato soltanto `KEY_VALUE_SET`. 
+ `keys` (obbligatorio): specifica le nuove chiavi e il valore di testo associato che il worker può aggiungere.
+ `no-key-edit` (obbligatorio): impedisce ai worker di modificare le chiavi delle annotazioni passate tramite `initialValue`.
+ `no-geometry-edit`: impedisce ai worker di modificare i poligoni delle annotazioni passate tramite `initialValue`.

Per gli elementi figlio dell'elemento `<crowd-textract-analyze-document>` sono necessarie due Regioni. Puoi utilizzare elementi HTML e CSS arbitrari in queste Regioni. 
+ `<full-instructions>`: le istruzioni disponibili dal collegamento **Visualizza istruzioni complete** nello strumento. Puoi lasciarlo vuoto, ma ti consigliamo di fornire istruzioni complete per ottenere risultati migliori.
+ `<short-instructions>`: una breve descrizione dell'attività visualizzata nella barra laterale dello strumento. Puoi lasciarlo vuoto, ma ti consigliamo di fornire istruzioni complete per ottenere risultati migliori.

 Un modello Amazon Textract è simile al seguente esempio.

**Example**  

```
<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>
{% capture s3_uri %}http://s3.amazonaws.com/{{ task.input.aiServiceRequest.document.s3Object.bucket }}/{{ task.input.aiServiceRequest.document.s3Object.name }}{% endcapture %}

<crowd-form>
  <crowd-textract-analyze-document
    src="{{ s3_uri | grant_read_access }}"
    initial-value="{{ task.input.selectedAiServiceResponse.blocks }}"
    header="Review the key-value pairs listed on the right and correct them if they don't match the following document."
    no-key-edit
    no-geometry-edit
    keys="{{ task.input.humanLoopContext.importantFormKeys }}"
    block-types="['KEY_VALUE_SET']"
  >
    <short-instructions header="Instructions">
      <style>
        .instructions {
          white-space: pre-wrap;
        }
        .instructionsImage {
          display: inline-block;
          max-width: 100%;
        }
      </style>
      <p class='instructions'>Choose a key-value block to highlight the corresponding key-value pair in the document.

If it is a valid key-value pair, review the content for the value. If the content is incorrect, correct it.

The text of the value is incorrect, correct it.
<img class='instructionsImage' src="https://example-site/correct-value-text.png" />

A wrong value is identified, correct it.
<img class='instructionsImage' src="https://example-site/correct-value.png" />

If it is not a valid key-value relationship, choose No.
<img class='instructionsImage' src="https://example-site/not-a-key-value-pair.png" />

If you can’t find the key in the document, choose Key not found.
<img class='instructionsImage' src="https://example-site/key-is-not-found.png" />

If the content of a field is empty, choose Value is blank.
<img class='instructionsImage' src="https://example-site/value-is-blank.png" />

<b>Examples</b>
Key and value are often displayed next to or below to each other.

Key and value displayed in one line.
<img class='instructionsImage' src="https://example-site/sample-key-value-pair-1.png" />

Key and value displayed in two lines.
<img class='instructionsImage' src="https://example-site/sample-key-value-pair-2.png" />

If the content of the value has multiple lines, enter all the text without a line break. Include all value text even if it extends beyond the highlight box.
<img class='instructionsImage' src="https://assets.crowd.aws/images/a2i-console/multiple-lines.png" /></p>
    </short-instructions>

    <full-instructions header="Instructions"></full-instructions>
  </crowd-textract-analyze-document>
</crowd-form>
```

## Esempio di modello personalizzato per Amazon Rekognition
<a name="a2i-custom-templates-rekognition-sample"></a>

Tutti i modelli personalizzati iniziano e terminano con gli elementi `<crowd-form> </crowd-form>`. Analogamente agli elementi HTML `<form>` standard, tutto il codice del modulo deve essere racchiuso tra questi elementi. Per un modello di attività Amazon Rekognition personalizzato, utilizza l'elemento `<crowd-rekognition-detect-moderation-labels>`. Questo elemento supporta i seguenti attributi: 
+ `categories`: un array di stringhe *o* un array di oggetti in cui ogni oggetto ha un campo `name`.
  + Se le categorie sono disponibili come oggetti, si applica quanto segue:
    + Le categorie visualizzate sono il valore del campo `name`. 
    + La risposta restituita contiene gli oggetti *completi* di ogni categoria selezionata.
  + Se le categorie sono disponibili come stringhe, si applica quanto segue:
    + La risposta restituita è un array di tutte le stringhe selezionate.
+ `exclusion-category`: impostando questo attributo, si crea un pulsante sotto le categorie nell'interfaccia utente. Quando un utente seleziona il pulsante, tutte le categorie vengono deselezionate e disabilitate. Se il worker seleziona nuovamente il pulsante, gli utenti possono di nuovo scegliere le categorie. Se il worker invia l'attività selezionando il pulsante **Invia** dopo aver selezionato questo pulsante, l'attività restituisce un array vuoto.

Per gli elementi figlio dell'elemento `<crowd-rekognition-detect-moderation-labels>` sono necessarie due Regioni.
+ `<full-instructions>`: le istruzioni disponibili dal collegamento **Visualizza istruzioni complete** nello strumento. Puoi lasciarlo vuoto, ma ti consigliamo di fornire istruzioni complete per ottenere risultati migliori.
+ `<short-instructions>`: breve descrizione dell'attività visualizzata nella barra laterale dello strumento. Puoi lasciarlo vuoto, ma ti consigliamo di fornire istruzioni complete per ottenere risultati migliori.

Un modello che utilizza questi elementi è simile al seguente esempio.

```
<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>
{% capture s3_uri %}http://s3.amazonaws.com/{{ task.input.aiServiceRequest.image.s3Object.bucket }}/{{ task.input.aiServiceRequest.image.s3Object.name }}{% endcapture %}

<crowd-form>
  <crowd-rekognition-detect-moderation-labels
    categories='[
      {% for label in task.input.selectedAiServiceResponse.moderationLabels %}
        {
          name: "{{ label.name }}",
          parentName: "{{ label.parentName }}",
        },
      {% endfor %}
    ]'
    src="{{ s3_uri | grant_read_access }}"
    header="Review the image and choose all applicable categories."
  >
    <short-instructions header="Instructions">
      <style>
        .instructions {
          white-space: pre-wrap;
        }
      </style>
      <p class='instructions'>Review the image and choose all applicable categories.
If no categories apply, choose None.

<b>Nudity</b>
Visuals depicting nude male or female person or persons

<b>Graphic Male Nudity</b>
Visuals depicting full frontal male nudity, often close ups

<b>Graphic Female Nudity</b>
Visuals depicting full frontal female nudity, often close ups

<b>Sexual Activity</b>
Visuals depicting various types of explicit sexual activities and pornography

<b>Illustrated Nudity or Sexual Activity</b>
Visuals depicting animated or drawn sexual activity, nudity, or pornography

<b>Adult Toys</b>
Visuals depicting adult toys, often in a marketing context

<b>Female Swimwear or Underwear</b>
Visuals depicting female person wearing only swimwear or underwear

<b>Male Swimwear Or Underwear</b>
Visuals depicting male person wearing only swimwear or underwear

<b>Partial Nudity</b>
Visuals depicting covered up nudity, for example using hands or pose

<b>Revealing Clothes</b>
Visuals depicting revealing clothes and poses, such as deep cut dresses

<b>Graphic Violence or Gore</b>
Visuals depicting prominent blood or bloody injuries

<b>Physical Violence</b>
Visuals depicting violent physical assault, such as kicking or punching

<b>Weapon Violence</b>
Visuals depicting violence using weapons like firearms or blades, such as shooting

<b>Weapons</b>
Visuals depicting weapons like firearms and blades

<b>Self Injury</b>
Visuals depicting self-inflicted cutting on the body, typically in distinctive patterns using sharp objects

<b>Emaciated Bodies</b>
Visuals depicting extremely malnourished human bodies

<b>Corpses</b>
Visuals depicting human dead bodies

<b>Hanging</b>
Visuals depicting death by hanging</p>
    </short-instructions>

    <full-instructions header="Instructions"></full-instructions>
  </crowd-rekognition-detect-moderation-labels>
</crowd-form>
```

## Aggiunta di automazione con Liquid
<a name="a2i-custom-templates-step2-automate"></a>

Il sistema di modello personalizzato utilizza [Liquid](https://shopify.github.io/liquid/) per l'automazione. *Liquid* è un linguaggio markup inline open-source. Per ulteriori informazioni e la documentazione, visita la [home page Liquid](https://shopify.github.io/liquid/).

In Liquid, il testo compreso tra parentesi graffe singole e simboli di percentuale è un'istruzione o un *tag* che svolge un operazione come un flusso di controllo o un’iterazione. Il testo racchiuso tra parentesi graffe doppie è una variabile o *oggetto* che genera il suo valore. L'elenco seguente include due tipi di tag Liquid che potresti trovare utili per automatizzare l'elaborazione dei dati di input dei modelli. Se selezioni uno dei seguenti tipi di tag, verrai reindirizzato alla documentazione di Liquid.
+ [Flusso di controllo](https://shopify.github.io/liquid/tags/control-flow/): include operatori logici di programmazione come`if/else`, `unless` e `case/when`.
+ [Iterazione](https://shopify.github.io/liquid/tags/iteration/): consente di eseguire ripetutamente blocchi di codice utilizzando istruzioni come i cicli for.

  Ad esempio, il seguente esempio di codice dimostra come utilizzare il tag Liquid `for` per creare un ciclo `for`. Questo esempio esegue un ciclo continuo di [https://docs.aws.amazon.com/rekognition/latest/dg/API_ModerationLabel.html](https://docs.aws.amazon.com/rekognition/latest/dg/API_ModerationLabel.html) restituiti da Amazon Rekognition e mostra gli attributi `moderationLabels` `name` e `parentName` per la revisione da parte dei worker:

  ```
   {% for label in task.input.selectedAiServiceResponse.moderationLabels %}
      {
        name: &quot;{{ label.name }}&quot;,
        parentName: &quot;{{ label.parentName }}&quot;,
      },
   {% endfor %}
  ```

### Utilizzo di filtri di variabili
<a name="a2i-custom-templates-step2-automate-filters"></a>

Oltre ai [filtri e alle operazioni Liquid](https://shopify.github.io/liquid/filters/abs/) standard, IA aumentata Amazon (Amazon A2I) offre alcuni filtri aggiuntivi. I filtri si applicano inserendo un carattere barra verticale (`|`) dopo il nome della variabile e quindi specificando il nome di un filtro. Per concatenare i filtri utilizza il seguente formato.

**Example**  

```
{{ <content> | <filter> | <filter> }}
```

#### Escape automatico ed escape esplicito
<a name="a2i-custom-templates-step2-automate-filters-autoescape"></a>

Per impostazione predefinita, gli input vengono preceduti da un carattere di escape HTML per evitare confusione tra testo variabile e HTML. Puoi aggiungere in maniera esplicita il filtro `escape` per rendere più evidente a chi legge il codice sorgente del modello dove si esegue l'escape.

#### escape\$1once
<a name="a2i-custom-templates-step2-automate-escapeonce"></a>

`escape_once` garantisce che se hai già eseguito l'escape del codice, questo non viene nuovamente sottoposto a escape. Ad esempio, garantisce che `&amp;` non diventi `&amp;amp;`.

#### skip\$1autoescape
<a name="a2i-custom-templates-step2-automate-skipautoescape"></a>

`skip_autoescape` è utile quando il contenuto deve essere utilizzato come HTML. Ad esempio, le istruzioni complete per un riquadro di delimitazione potrebbero contenere qualche paragrafo di testo e alcune immagini.

**Nota**  
Usa `skip_autoescape` con parsimonia. La best practice per i modelli è evitare di passare codice funzionale o markup con `skip_autoescape` a meno che non sei assolutamente certo di avere il controllo rigoroso di ciò che viene passato. Se stai passando input utente, potresti esporre i worker a un attacco Cross-site scripting.

#### to\$1json
<a name="a2i-custom-templates-step2-automate-tojson"></a>

`to_json`codifica i dati forniti a JavaScript Object Notation (JSON). Se fornisci un oggetto, lo serializza.

#### grant\$1read\$1access
<a name="a2i-custom-templates-step2-automate-grantreadaccess"></a>

`grant_read_access` accetta un URI Amazon Simple Storage Service (Amazon S3) e lo codifica in un URL HTTPS con un token di accesso di breve durata per tale risorsa. Questo consente di visualizzare oggetti foto, audio o video archiviati in bucket S3 che non sono altrimenti accessibili pubblicamente dai worker.

#### s3\$1presign
<a name="a2i-custom-templates-step2-automate-s3"></a>

 Il filtro `s3_presign` funziona allo stesso modo del filtro `grant_read_access`. `s3_presign` accetta un URI Amazon S3 e lo codifica in un URL HTTPS con un token di accesso di breve durata per tale risorsa. Questo consente di visualizzare oggetti foto, audio o video archiviati in bucket S3 che non sono altrimenti accessibili pubblicamente dai worker.

**Example Esempio di filtri di variabili**  
Input  

```
auto-escape: {{ "Have you read 'James & the Giant Peach'?" }}
explicit escape: {{ "Have you read 'James & the Giant Peach'?" | escape }}
explicit escape_once: {{ "Have you read 'James &amp; the Giant Peach'?" | escape_once }}
skip_autoescape: {{ "Have you read 'James & the Giant Peach'?" | skip_autoescape }}
to_json: {{ jsObject | to_json }}                
grant_read_access: {{ "s3://amzn-s3-demo-bucket/myphoto.png" | grant_read_access }}
s3_presign: {{ "s3://amzn-s3-demo-bucket/myphoto.png" | s3_presign }}
```

**Example**  
Output  

```
auto-escape: Have you read &#39;James &amp; the Giant Peach&#39;?
explicit escape: Have you read &#39;James &amp; the Giant Peach&#39;?
explicit escape_once: Have you read &#39;James &amp; the Giant Peach&#39;?
skip_autoescape: Have you read 'James & the Giant Peach'?
to_json: { "point_number": 8, "coords": [ 59, 76 ] }
grant_read_access: https://s3.amazonaws.com/amzn-s3-demo-bucket/myphoto.png?<access token and other params>
s3_presign: https://s3.amazonaws.com/amzn-s3-demo-bucket/myphoto.png?<access token and other params>
```

**Example Esempio di modello di classificazione automatizzato**  
Per automatizzare questo semplice esempio di classificazione del testo, includi il tag Liquid `{{ task.input.source }}`. In questo esempio viene utilizzato l'elemento [crowd-classifier](sms-ui-template-crowd-classifier.md).  

```
<script src="https://assets.crowd.aws/crowd-html-elements.js"></script>
<crowd-form>
  <crowd-classifier 
    name="tweetFeeling"
    categories="['positive', 'negative', 'neutral', 'cannot determine']"
    header="Which term best describes this tweet?" 
  >
    <classification-target>
       {{ task.input.source }}
    </classification-target>

    <full-instructions header="Analyzing a sentiment">
      Try to determine the feeling the author 
      of the tweet is trying to express. 
      If none seems to match, choose "other."
    </full-instructions>

    <short-instructions>
      Pick the term that best describes the sentiment 
      of the tweet. 
    </short-instructions>

  </crowd-classifier>
</crowd-form>
```

## Anteprima di un modello di attività del worker
<a name="a2i-preview-your-custom-template"></a>

Per visualizzare in anteprima un modello di attività di lavoro personalizzato, utilizza l' SageMaker operazione AI. `RenderUiTemplate` Puoi utilizzare l'`RenderUiTemplate`operazione con l'SDK AWS CLI o con il tuo AWS SDK preferito. Per la documentazione sulla lingua supportata specifica SDKs per questa operazione API, consulta la [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_RenderUiTemplate.html#API_RenderUiTemplate_SeeAlso](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_RenderUiTemplate.html#API_RenderUiTemplate_SeeAlso)sezione di. [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_RenderUiTemplate.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_RenderUiTemplate.html) 

**Prerequisiti**

Per visualizzare in anteprima il modello di task di lavoro, il ruolo AWS Identity and Access Management (IAM) Amazon Resource Name (ARN) o `RoleArn` che utilizzi devi disporre dell'autorizzazione per accedere agli oggetti S3 utilizzati dal modello. Per informazioni su come configurare il ruolo o l'utente, consulta [Abilitazione delle anteprime dei modelli di attività del worker](a2i-permissions-security.md#permissions-for-worker-task-templates-augmented-ai).

**Per visualizzare in anteprima il modello di attività del worker utilizzando l'operazione `RenderUiTemplate`:**

1. Fornisci il **`RoleArn`** di un ruolo con le policy richieste collegate per visualizzare in anteprima il modello personalizzato. 

1. Nel parametro **`Input`** di **`Task`**, fornisci un oggetto JSON contenente i valori per le variabili definite nel modello. Queste sono le variabili che vengono sostituite alla variabile `task.input.source`. Ad esempio, se definisci una variabile task.input.text nel modello, puoi fornire la variabile nell'oggetto JSON come `text`: `sample text`.

1. Nel parametro **`Content`** di **`UiTemplate`** inserisci il modello.

Una volta configurato `RenderUiTemplate`, utilizza l'SDK preferito o l' AWS CLI per inviare una richiesta per eseguire il rendering del modello. Se la richiesta ha esito positivo, la risposta include [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_RenderUiTemplate.html#API_RenderUiTemplate_ResponseSyntax](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_RenderUiTemplate.html#API_RenderUiTemplate_ResponseSyntax), un modello Liquid che esegue il rendering dell'HTML per l'interfaccia utente del worker.

**Importante**  
Per visualizzare il modello in anteprima, è necessario un ruolo IAM con le autorizzazioni per leggere gli oggetti Amazon S3 che vengono visualizzati nell'interfaccia utente. Per una policy di esempio che puoi collegare al ruolo IAM per concedere queste autorizzazioni, consulta [Abilitazione delle anteprime dei modelli di attività del worker](a2i-permissions-security.md#permissions-for-worker-task-templates-augmented-ai).