Documentação Guia do desenvolvedor do Target

Gerencie seu catálogo do Recommendations usando APIs

Last update: Sat Jul 20 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Tópicos:

Criado para:

undefined

Ao garantir que você atenda aos requisitos para usar a API de Recommendations, você aprendeu a gerar um token de acesso usando o fluxo de autenticação JWT para usar as APIs de Administrador Adobe Target na Adobe Developer Console.

Agora você pode usar as APIs do Recommendations para adicionar, atualizar ou excluir itens do catálogo de recomendações. Assim como no restante das APIs de administrador do Adobe Target, as APIs do Recommendations exigem autenticação.

NOTE

Envie a solicitação IMS: JWT Generate + Auth via User Token sempre que precisar atualizar o token de acesso para autenticação, pois ela expira após 24 horas. Consulte Configurar a autenticação da API do Adobe para obter instruções.

JWT3ff

Antes de continuar, obtenha a coleção do Recommendations Postman.

Criação e atualização de itens com a API Salvar entidades

Para preencher o banco de dados de produtos do Recommendations usando a API em vez de um feed de produto CSV ou de solicitações do Target sendo acionadas nas páginas de produtos, use a API Salvar Entidades. Esta solicitação adiciona ou atualiza um item em um único ambiente do Target. A sintaxe é:

POST https://mc.adobe.io/{{TENANT_ID}}/target/recs/entities

Por exemplo, Salvar Entidades pode ser usado para atualizar itens sempre que certos limites forem atingidos - como limites para estoque ou preço - para sinalizar esses itens e evitar que eles sejam recomendados.

Navegue até Target > Setup > Hosts > CONTROL Environments para obter a ID de Ambiente de Destino na qual você deseja adicionar ou atualizar um item.
Verifique se TENANT_ID e API_KEY fazem referência às variáveis de ambiente do Postman estabelecidas anteriormente. Use a imagem abaixo para comparação. Se necessário, modifique os cabeçalhos e o caminho na solicitação de API para corresponder aos da imagem abaixo.

Insira seu JSON como código raw no Corpo. Não se esqueça de especificar sua ID de ambiente, usando a variável environment. (No exemplo abaixo, a ID de ambiente é 6781.)

Abaixo está um exemplo de JSON que adiciona o entity.id kit2001 com valores de entidade associados para um produto de Forno de torradeira, no ambiente 6781.

code language-none

code language-none
`{ "entities": [{ "name": "Toaster Oven", "id": "kit2001", "environment": 6781, "categories": [ "housewares:appliances" ], "attributes": { "inventory": 77, "margin": 23, "message": "crashing helicopter", "pageUrl": "www.foobar.foo.com/helicopter.html", "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg", "value": 19.2 } }] }`

    {
    "entities": [{
            "name": "Toaster Oven",
            "id": "kit2001",
            "environment": 6781,
            "categories": [
                "housewares:appliances"
            ],
            "attributes": {
                "inventory": 77,
                "margin": 23,
                "message": "crashing helicopter",
                "pageUrl": "www.foobar.foo.com/helicopter.html",
                "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg",
               "value": 19.2
            }
        }]
    }

Clique em Send. Você deve receber a seguinte resposta.

O objeto JSON pode ser dimensionado para enviar vários produtos. Por exemplo, esse JSON especifica duas entidades.

code language-none

code language-none
{ "entities": [{ "name": "Toaster Oven", "id": "kit2001", "environment": 6781, "categories": [ "housewares:appliances" ], "attributes": { "inventory": 89, "margin": 11, "message": "Toaster Oven", "pageUrl": "www.foobar.foo.com/helicopter.html", "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg", "value": 102.5 } }, { "name": "Blender", "id": "kit2002", "environment": 6781, "categories": [ "housewares:appliances" ], "attributes": { "inventory": 36, "margin": 5, "message": "Blender", "pageUrl": "www.foobar.foo.com/helicopter.html", "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg", "value": 54.5 } } ] }

    {
        "entities": [{
                "name": "Toaster Oven",
                "id": "kit2001",
                "environment": 6781,
                "categories": [
                    "housewares:appliances"
                ],
                "attributes": {
                    "inventory": 89,
                    "margin": 11,
                    "message": "Toaster Oven",
                    "pageUrl": "www.foobar.foo.com/helicopter.html",
                    "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg",
                    "value": 102.5
                }
            },
            {
                "name": "Blender",
                "id": "kit2002",
                "environment": 6781,
                "categories": [
                    "housewares:appliances"
                ],
                "attributes": {
                    "inventory": 36,
                    "margin": 5,
                    "message": "Blender",
                    "pageUrl": "www.foobar.foo.com/helicopter.html",
                    "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg",
                    "value": 54.5
                }
            }
        ]
    }

Agora é a sua vez! Use a API Save Entities para adicionar os seguintes itens ao catálogo. Use a amostra JSON acima como ponto de partida. (Será necessário estender o JSON para incluir entidades adicionais.)

Parece que esses dois últimos itens não pertencem. Vamos inspecioná-los usando a API Get Entity e, se necessário, excluí-los usando a API Delete Entities.

Obter detalhes do item com a API Obter entidade

Para recuperar os detalhes de um item existente, use a Obter API de Entidade. A sintaxe é:

GET https://mc.adobe.io/{{TENANT_ID}}/target/recs/entities/[entity.id]

Os detalhes da entidade só podem ser recuperados para uma única entidade de cada vez. Você pode usar Obter entidade para confirmar que as atualizações foram feitas no catálogo conforme esperado ou para auditar o conteúdo do catálogo de outra forma.

Na solicitação de API, especifique a ID da entidade, usando a variável entityId. O exemplo a seguir retornará detalhes para a entidade cuja entityId=kit2004.
Verifique se TENANT_ID e API_KEY fazem referência às variáveis de ambiente do Postman estabelecidas anteriormente. Use a imagem abaixo para comparação. Se necessário, modifique os cabeçalhos e o caminho na solicitação de API para corresponder aos da imagem abaixo.

Envie a solicitação.

GetEntity3
Se você receber um erro informando que a entidade não foi encontrada, como mostrado no exemplo acima, verifique se está enviando a solicitação para o ambiente correto do Target.

note note
NOTE
Se nenhum ambiente for especificado explicitamente, Obter Entidade tentará obter a entidade somente do seu ambiente padrão. Se quiser extrair de qualquer ambiente que não seja o ambiente padrão, especifique a ID do ambiente.

Se necessário, adicione o parâmetro environmentId e reenvie a solicitação.
Envie outra solicitação Get Entity, desta vez para inspecionar a entidade cuja entityId=kit2005.

Suponha que você decida que essas entidades precisam ser removidas do catálogo. Vamos usar a API Delete Entities.

Exclusão de itens com a API Excluir entidades

Para remover itens do catálogo, use a API de Exclusão de Entidades. A sintaxe é:

DELETE https://mc.adobe.io/{{TENANT_ID}}/target/recs/entities?ids=[comma-delimited-entity-ids]&environment=[environmentId]

WARNING

A API Excluir entidades exclui entidades referenciadas pelas IDs especificadas. Se nenhuma ID de entidade for fornecida, todas as entidades em um determinado ambiente serão excluídas. Se nenhuma ID de ambiente for fornecida, as entidades serão excluídas de todos os ambientes. Use isso com cuidado!

Navegue até Target > Setup > Hosts > Environments para obter a ID de Ambiente de Destino da qual deseja excluir itens.
Na solicitação de API, especifique as IDs de entidade das entidades que deseja excluir, usando a sintaxe &ids=[comma-delimited-entity-ids] (um parâmetro de consulta). Ao excluir mais de uma entidade, separe as IDs usando vírgulas.
Especifique a ID de ambiente, usando a sintaxe &environment=[environmentId]; caso contrário, as entidades em todos os ambientes serão excluídas.
Verifique se TENANT_ID e API_KEY fazem referência às variáveis de ambiente do Postman estabelecidas anteriormente. Use a imagem abaixo para comparação. Se necessário, modifique os cabeçalhos e o caminho na solicitação de API para corresponder aos da imagem abaixo.
Envie a solicitação.
Verifique os resultados usando Get Entity, que agora deve indicar que as entidades excluídas não foram encontradas.

Parabéns! Agora você pode usar as APIs do Recommendations para criar, atualizar, excluir e obter detalhes sobre as entidades no catálogo. Na próxima seção, você aprenderá a gerenciar critérios personalizados.

<!— Próximo "Gerenciar Critérios Personalizados" > —>

recommendation-more-help

6906415f-169c-422b-89d3-7118e147c4e3