As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Como filtrar recomendações em tempo real
Você pode filtrar recomendações em tempo real com o console Amazon Personalize, AWS Command Line Interface (AWS CLI) ou o. AWS SDKs
Ao obter recomendações de itens personalizadas ou itens semelhantes, é possível especificar uma promoção na solicitação. Uma *promoção* usa um filtro para definir regras de negócios adicionais que se aplicam a um subconjunto configurável de itens recomendados. Para obter mais informações, consulte [Promover itens nas recomendações em tempo real](promoting-items.md).
**Topics**
+ [Como filtrar recomendações em tempo real (console)](#filter-rt-console)
+ [Como filtrar recomendações em tempo real (AWS CLI)](#filter-rt-cli)
+ [Como filtrar recomendações em tempo real (AWS SDKs)](#filter-rt-sdk)
## Como filtrar recomendações em tempo real (console)
Para usar o console e filtrar recomendações em tempo real, crie um filtro e aplique-o a uma solicitação de recomendação.
**nota**
Para filtrar recomendações usando um filtro com parâmetros e uma campanha implantada antes de 10 de novembro de 2020, você deve reimplantar a campanha usando a operação [UpdateCampaign](API_UpdateCampaign.md) ou criar uma nova campanha.
### Como criar um filtro (console)
Para criar um filtro no console, escolha o grupo de conjuntos de dados que contém a campanha ou o recomendador que você deseja usar para obter recomendações filtradas. Em seguida, forneça um nome de filtro e uma expressão de filtro.
**Para criar um filtro (console)**
1. Abra o console Amazon Personalize em [https://console.aws.amazon.com/personalize/casa](https://console.aws.amazon.com/personalize/home) e faça login na sua conta.
1. Escolha o grupo de conjuntos de dados que contém a campanha ou o recomendador que você deseja usar para obter recomendações filtradas.
1. Na página de navegação, selecione **Filtros** e, depois, **Criar filtro**. A página **Criar filtro** é exibida.
![\[Representa a página de criação de filtro com campos de nome e expressão do filtro.\]](http://docs.aws.amazon.com/pt_br/personalize/latest/dg/images/create-filter-page.png)
1. Em **Nome do filtro**, insira um nome para o filtro. Você escolherá o filtro com esse nome ao aplicá-lo a uma solicitação de recomendação.
1. Para **Expressão**, escolha **Criar expressão** ou **Adicionar expressão manualmente** e crie ou insira sua expressão:
+ Para usar o construtor de expressões, escolha **Criar expressão**. O construtor de expressões fornece estrutura, campos e diretrizes para criar expressões de filtro formatadas corretamente. Para obter mais informações, consulte [Como usar o construtor de expressões de filtro](#using-filter-expression-builder).
+ Para inserir sua própria expressão, escolha **Adicionar expressão manualmente**. Para obter mais informações, consulte [Filtrar elementos de expressão](creating-filter-expressions.md#filter-expression-elements).
1. Escolha **Concluir**. A página de visão geral do filtro mostra o nome do recurso da Amazon (ARN), o status e a expressão completa do filtro. Para excluir o filtro, escolha **Excluir**. Para obter informações sobre como encontrar e excluir filtros depois de sair da página de visão geral, consulte [Como excluir um filtro (console)](#delete-filter-console).
![\[Representa a página de detalhes do filtro com o ARN e a expressão do filtro.\]](http://docs.aws.amazon.com/pt_br/personalize/latest/dg/images/filter-details-page.png)
### Como aplicar um filtro (console)
Para aplicar um filtro, em **Testar recomendador** (para recomendadores) ou **Testar resultados da campanha** (para campanhas personalizadas), selecione o filtro e insira os valores dos parâmetros do filtro. Em seguida, obtenha as recomendações para um usuário.
**Importante**
Para expressões de filtro que usem um elemento `INCLUDE`, é necessário fornecer valores para todos os parâmetros definidos na expressão. Para filtros com expressões que usem um elemento `EXCLUDE`, é possível omitir os `filter-values`. Nesse caso, o Amazon Personalize não usa essa parte da expressão para filtrar recomendações.
**Para aplicar um filtro (console)**
1. Abra o console Amazon Personalize em [https://console.aws.amazon.com/personalize/casa](https://console.aws.amazon.com/personalize/home) e faça login na sua conta.
1. Escolha o grupo de conjuntos de dados que contém a campanha ou o recomendador que você deseja usar para obter recomendações filtradas.
1. Dependendo do tipo do grupo de conjuntos de dados ou do tipo de recurso, realize uma das seguintes ações:
1. Para um grupo de conjuntos de dados de domínio, no painel de navegação, escolha **Recomendadores**.
1. Para um grupo de conjuntos de dados ou recursos personalizados, no painel de navegação, selecione **Recursos personalizados** e escolha **Campanhas**.
1. Na página **Recomendadores** ou **Campanhas**, escolha o recomendador ou a campanha-alvo.
1. A título de comparação, comece obtendo recomendações sem aplicar um filtro. Em **Testar recomendador**/**Testar resultados da campanha**, insira o ID do usuário para o qual deseja obter recomendações, ou os IDs dos itens relacionados, e selecione **Obter recomendações**. Será exibida uma tabela com as principais recomendações.
![\[Representa os resultados das recomendações sem aplicar um filtro.\]](http://docs.aws.amazon.com/pt_br/personalize/latest/dg/images/Recommendations_no-filter.PNG)
1. Em **Nome do filtro**, escolha o filtro criado. Se o filtro tiver algum parâmetro de espaço reservado, os campos associados a cada parâmetro serão exibidos.
1. Se você estiver usando um filtro com parâmetros de espaço reservado, insira o valor para definir os critérios do filtro em cada parâmetro. Para usar vários valores em um parâmetro, separe cada um deles com uma vírgula.
1. Usando o mesmo `User ID` ou `Item ID` na etapa anterior, selecione **Obter recomendações**. A tabela de recomendações será exibida.
![\[Representa os resultados da recomendação com um filtro aplicado.\]](http://docs.aws.amazon.com/pt_br/personalize/latest/dg/images/Recommendations_filter.png)
Por exemplo, se o usuário já tiver comprado um item recomendado, o filtro o removerá da lista de recomendações. Neste exemplo, os itens 2657, 2985 foram substituídos pelos itens mais adequados que o usuário não comprou (itens 2641 e 1573).
### Como usar o construtor de expressões de filtro
O **construtor de expressões** na página **Criar filtro** fornece a estrutura, os campos e as diretrizes para criar um filtro formatado corretamente.
![\[Representa os campos do construtor de expressões na página de criação do filtro.\]](http://docs.aws.amazon.com/pt_br/personalize/latest/dg/images/expression-builder-empty.png)
Para criar uma expressão de filtro:
+ Use os campos **Tipo**, **Ação**, **Propriedade**, **Operador** e **Valor** para criar uma expressão.
Insira um valor fixo em **Valor** ou, para definir critérios de filtro ao receber recomendações, insira *\$1* \$1 um nome de parâmetro. Por exemplo, .`$GENRES` Ao receber recomendações, você fornecerá o(s) valor(es) para filtrar. Neste exemplo, você forneceria um gênero ou uma lista de gêneros ao receber recomendações.
Separe vários valores que não são parâmetros com uma vírgula. Não é possível adicionar parâmetros separados por vírgula a um filtro.
**nota**
Depois de escolher uma **propriedade** (no formato `dataset.field`), o valor de **propriedade** para todas as linhas sucessivas encadeadas por condições `OR` ou `AND` deve usar o mesmo `dataset`.
+ Use os botões **\$1** e **X** para adicionar ou excluir uma linha da sua expressão. Não é possível excluir a primeira linha.
+ Para novas linhas, use os operadores `AND`, `IF` ou `OR` no menu **E** para criar um encadeamento de condições.
Para condições `IF`:
+ Cada expressão pode conter apenas um item `IF`. Se você remover uma condição IF, o Construtor de expressões removerá todas as condições `AND` subsequentes.
+ É possível usar condições `IF` para expressões filtradas por `CurrentUser`.
+ Selecione o botão **Adicionar expressão** para adicionar outra expressão de filtro para realizar uma filtragem mais precisa. Cada expressão é avaliada primeiro de forma independente, e o resultado é uma união dos dois resultados.
**nota**
Para criar um filtro que use conjuntos de dados de itens e de interações com itens ou conjuntos de dados de ações ou de interações com ações, *é necessário* usar várias expressões.
#### Exemplo de construtor de expressão
O exemplo a seguir mostra como criar um filtro que exclui itens com um gênero que você especifica ao receber recomendações (observe o parâmetro de espaço reservado \$1GENRES). O filtro também exclui itens com `DOWNLOAD_COUNT` maior que `200`, mas somente se a idade do usuário atual for maior que `17`.
![\[Mostra como usar o construtor de expressões para criar um exemplo de expressão de filtro.\]](http://docs.aws.amazon.com/pt_br/personalize/latest/dg/images/create-filter-expression-builder.png)
### Como excluir um filtro (console)
Excluir um filtro o remove da lista de filtros de um grupo de conjuntos de dados.
**Importante**
Não é possível excluir um filtro enquanto um trabalho de inferência em lote está em andamento.
**Para excluir um filtro (console)**
1. Abra o console Amazon Personalize em [https://console.aws.amazon.com/personalize/casa](https://console.aws.amazon.com/personalize/home) e faça login na sua conta.
1. Na lista **Grupos de conjuntos de dados**, escolha o grupo de conjuntos de dados que contém o filtro que você deseja excluir.
1. No painel de navegação, escolha **Métricas**.
1. Na lista de filtros, escolha o filtro que deseja excluir e depois **Visualizar detalhes**. A página de detalhes do filtro é exibida.
1. Escolha **Excluir** e confirme a exclusão na caixa de diálogo de confirmação.
## Como filtrar recomendações em tempo real (AWS CLI)
Para filtrar recomendações usando o AWS CLI, você cria um filtro e o aplica especificando o ARN do filtro em [GetRecommendations](API_RS_GetRecommendations.md) uma [GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md) solicitação or.
**Importante**
Para filtrar recomendações usando um filtro com parâmetros e uma campanha que você implantou antes de 10 de novembro de 2020, você deve reimplantar a campanha usando a chamada a [UpdateCampaign](API_UpdateCampaign.md) ou criar uma nova campanha.
### Como criar um filtro (AWS CLI)
Use a operação `create-filter` a seguir para criar um filtro e especificar a expressão do filtro.
Substitua o `Filter name` pelo nome do filtro e `Dataset group ARN` pelo nome do recurso da Amazon (ARN) do grupo de conjuntos de dados. Substitua a amostra `filter-expression` por sua própria expressão de filtro.
```
aws personalize create-filter \
--name Filter name \
--dataset-group-arn dataset group arn \
--filter-expression "EXCLUDE ItemID WHERE Items.CATEGORY IN (\"$CATEGORY\")"
```
Se o processo for bem-sucedido, o ARN do filtro será exibido. Salve para uso posterior. Para verificar se o filtro está ativo, use a operação [DescribeFilter](API_DescribeFilter.md) antes de utilizar o filtro.
Para obter mais informações sobre a API, consulte [CreateFilter](API_CreateFilter.md). Para obter mais informações e exemplos sobre expressões de filtro, consulte [Estrutura e elementos das expressões de filtro](creating-filter-expressions.md).
### Como aplicar um filtro (AWS CLI)
Ao usar as operações `get-recommendations`, `get-action-recommendations` ou `get-personalized-ranking`, aplique um filtro enviando o `filter-arn` e todos os valores de filtro como parâmetros.
Confira a seguir um exemplo da operação `get-recommendations`. Substitua `Campaign ARN` pelo nome do recurso da Amazon (ARN) da sua campanha, `User ID` pelo ID do usuário para o qual você está recebendo recomendações e `Filter ARN` pelo ARN do seu filtro. Se você estiver recebendo recomendações de um recomendador em vez de uma campanha, use `recommender-arn` em vez de `--campaign-arn` e forneça o ARN para o recomendador.
Se sua expressão tiver algum parâmetro, inclua o objeto `filter-values`. Para cada parâmetro na sua expressão de filtro, forneça o nome do parâmetro (com distinção entre maiúsculas e minúsculas) e os valores. Por exemplo, se sua expressão tiver um parâmetro `$GENRE`, forneça *"GENRE"* como chave e um ou mais gêneros, por exemplo `"Comedy"`, como o valor. Separe vários valores com uma vírgula. Por exemplo, .`"\"comedy\",\"drama\",\"horror"\"`
**Importante**
Para expressões de filtro que usam um elemento `INCLUDE` para incluir itens, você deve fornecer valores para todos os parâmetros definidos na expressão. Para filtros com expressões que usam um elemento `EXCLUDE` para excluir itens, você pode omitir `filter-values`. Nesse caso, o Amazon Personalize não usa essa parte da expressão para filtrar recomendações.
```
aws personalize-runtime get-recommendations \
--campaign-arn Campaign ARN \
--user-id User ID \
--filter-arn Filter ARN \
--filter-values '{
"Parameter name": "\"value\"",
"Parameter name": "\"value1\",\"value2\",\"value3\""
}'
```
### Como excluir um filtro (AWS CLI)
Use a operação `delete-filter` a seguir para excluir um filtro. Substitua `filter ARN` pelo ARN do filtro.
```
aws personalize delete-filter --filter-arn Filter ARN
```
## Como filtrar recomendações em tempo real (AWS SDKs)
Para filtrar recomendações usando o AWS SDKs, você cria um filtro e o aplica especificando o ARN do filtro em [GetRecommendations](API_RS_GetRecommendations.md) uma [GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md) solicitação or.
**Importante**
Para filtrar recomendações usando um filtro com parâmetros e uma campanha que você implantou antes de 10 de novembro de 2020, você deve reimplantar a campanha usando a chamada a [UpdateCampaign](API_UpdateCampaign.md) ou criar uma nova campanha.
### Como criar um filtro (AWS SDKs)
Crie um novo filtro com a operação [CreateFilter](API_CreateFilter.md). O código a seguir mostra como criar um filtro. Especifique o nome do filtro, nome do recurso da Amazon (ARN) do seu grupo de conjuntos de dados e forneça sua expressão de filtro.
------
#### [ SDK for Python (Boto3) ]
```
import boto3
personalize = boto3.client('personalize')
response = personalize.create_filter(
name = 'Filter Name',
datasetGroupArn = 'Dataset Group ARN',
filterExpression = 'EXCLUDE ItemID WHERE Items.CATEGORY IN ($CATEGORY)'
)
filter_arn = response["filterArn"]
print("Filter ARN: " + filter_arn)
```
------
#### [ SDK for Java 2.x ]
```
public static String createFilter(PersonalizeClient personalizeClient,
String filterName,
String datasetGroupArn,
String filterExpression) {
try {
CreateFilterRequest request = CreateFilterRequest.builder()
.name(filterName)
.datasetGroupArn(datasetGroupArn)
.filterExpression(filterExpression)
.build();
return personalizeClient.createFilter(request).filterArn();
}
catch(PersonalizeException e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
return "";
}
```
------
#### [ SDK for JavaScript v3 ]
```
// Get service clients module and commands using ES6 syntax.
import { CreateFilterCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});
// Set the filter's parameters.
export const createFilterParam = {
datasetGroupArn: "DATASET_GROUP_ARN" /* required */,
name: "NAME" /* required */,
filterExpression: "FILTER_EXPRESSION" /*required */,
};
export const run = async () => {
try {
const response = await personalizeClient.send(
new CreateFilterCommand(createFilterParam),
);
console.log("Success", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
------
Registre o ARN do filtro para uso posterior. Para verificar se o filtro está ativo, use a operação [DescribeFilter](API_DescribeFilter.md) antes de utilizar o filtro. Para obter mais informações sobre a API, consulte [CreateFilter](API_CreateFilter.md). Para obter mais informações e exemplos sobre expressões de filtro, consulte [Estrutura e elementos das expressões de filtro](creating-filter-expressions.md).
### Como aplicar um filtro (AWS SDKs)
Ao usar as GetPersonalizedRanking operações GetRecommendations GetActionRecommendations, ou, aplique um filtro passando um `filterArn` e quaisquer valores de filtro como parâmetros.
O código a seguir mostra como obter recomendações filtradas de itens do Amazon Personalize para um usuário. Especifique o ID do usuário para que você deseja obter recomendações, o nome do recurso da Amazon (ARN) da sua campanha e o ARN do seu filtro. Se você estiver recebendo recomendações de um recomendador em vez de uma campanha, use `recommenderArn` em vez de `campaignArn` e forneça o ARN para o recomendador.
Para cada `filterValues` em cada parâmetro opcional na sua expressão de filtro, forneça o nome do parâmetro (com distinção entre maiúsculas e minúsculas) e os valores. Por exemplo, se sua expressão tiver um parâmetro `$GENRES`, forneça *"GENRES"* como chave e um ou mais gêneros, por exemplo `"\"Comedy"\"`, como o valor. Para usar vários valores, separe cada um deles com uma vírgula. Por exemplo, .`"\"comedy\",\"drama\",\"horror\""`
**Importante**
Para expressões de filtro que usam um elemento `INCLUDE` para incluir itens, você deve fornecer valores para todos os parâmetros definidos na expressão. Para filtros com expressões que usam um elemento `EXCLUDE` para excluir itens, você pode omitir `filter-values`. Nesse caso, o Amazon Personalize não usa essa parte da expressão para filtrar recomendações.
------
#### [ SDK for Python (Boto3) ]
```
import boto3
personalize_runtime = boto3.client("personalize-runtime")
response = personalize_runtime.get_recommendations(
campaignArn = "Campaign ARN",
userId = "User ID",
filterArn = "Filter ARN",
filterValues = {
"Parameter name": "\"value1\"",
"Parameter name": "\"value1\",\"value2\",\"value3\""
....
}
)
```
------
#### [ SDK for Java 2.x ]
O exemplo a seguir usa dois parâmetros, um com dois valores e outro com um valor. Dependendo da sua expressão de filtro, modifique o código para adicionar ou remover os campos parameterName e parameterValue.
```
public static void getFilteredRecs(PersonalizeRuntimeClient personalizeRuntimeClient,
String campaignArn,
String userId,
String filterArn,
String parameter1Name,
String parameter1Value1,
String parameter1Value2,
String parameter2Name,
String parameter2Value){
try {
Map filterValues = new HashMap<>();
filterValues.put(parameter1Name, String.format("\"%1$s\",\"%2$s\"",
parameter1Value1, parameter1Value2));
filterValues.put(parameter2Name, String.format("\"%1$s\"",
parameter2Value));
GetRecommendationsRequest recommendationsRequest = GetRecommendationsRequest.builder()
.campaignArn(campaignArn)
.numResults(20)
.userId(userId)
.filterArn(filterArn)
.filterValues(filterValues)
.build();
GetRecommendationsResponse recommendationsResponse = personalizeRuntimeClient.getRecommendations(recommendationsRequest);
List items = recommendationsResponse.itemList();
for (PredictedItem item: items) {
System.out.println("Item Id is : "+item.itemId());
System.out.println("Item score is : "+item.score());
}
} catch (PersonalizeRuntimeException e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
```
------
#### [ SDK for JavaScript v3 ]
```
// Get service clients module and commands using ES6 syntax.
import { GetRecommendationsCommand } from "@aws-sdk/client-personalize-runtime";
import { personalizeRuntimeClient } from "./libs/personalizeClients.js";
// Or, create the client here:
// const personalizeRuntimeClient = new PersonalizeRuntimeClient({ region: "REGION"});
// Set recommendation request parameters.
export const getRecommendationsParam = {
campaignArn: "CAMPAIGN_ARN" /* required */,
userId: "USER_ID" /* required */,
numResults: 15 /* optional */,
filterArn: "FILTER_ARN" /* required to filter recommendations */,
filterValues: {
PROPERTY:
'"VALUE"' /* Only required if your filter has a placeholder parameter */,
},
};
export const run = async () => {
try {
const response = await personalizeRuntimeClient.send(
new GetRecommendationsCommand(getRecommendationsParam),
);
console.log("Success!", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
------
### Excluindo um filtro (AWS Python SDK)
Use o método `delete_filter` a seguir para excluir um filtro. Substitua `filter ARN` pelo ARN do filtro.
```
import boto3
personalize = boto3.client("personalize")
response = personalize.delete_filter(
filterArn = "filter ARN"
)
```