# Conexão ao Salesforce Commerce Cloud A API B2C Commerce é um conjunto de APIs RESTful para interagir com instâncias do B2C Commerce. Ela é conhecida por alguns nomes diferentes: Salesforce Commerce API, o acrônimo SCAPI ou apenas Commerce API. A API permite aos desenvolvedores criar uma ampla variedade de aplicações, como lojas completas ou ferramentas comerciais personalizadas, para aprimorar o Business Manager. Para todos os clientes do B2C Commerce, a API está disponível sem custo adicional. A API é dividida em dois grupos principais: APIs de compradores e APIs de administradores. Dentro de cada grupo, elas também são divididas em famílias de APIs e em grupos menores focados em funcionalidades relacionadas. **Topics** + [Suporte do AWS Glue para o Salesforce Commerce Cloud](salesforce-commerce-cloud-support.md) + [Políticas que contêm as operações de API para criar e usar conexões](salesforce-commerce-cloud-configuring-iam-permissions.md) + [Configuração do Salesforce Commerce Cloud](salesforce-commerce-cloud-configuring.md) + [Configuração de conexões do Salesforce Commerce Cloud](salesforce-commerce-cloud-configuring-connections.md) + [Leitura de entidades do Salesforce Commerce Cloud](salesforce-commerce-cloud-reading-from-entities.md) + [Referência de opções de conexão do Salesforce Commerce Cloud](salesforce-commerce-cloud-connection-options.md) + [Limitações](salesforce-commerce-cloud-connector-limitations.md) # Suporte do AWS Glue para o Salesforce Commerce Cloud O AWS Glue oferece suporte ao Salesforce Commerce Cloud da seguinte forma: **Compatível como fonte?** Sim. Você pode usar trabalhos de ETL do AWS Glue para consultar dados do Salesforce Commerce Cloud. **Compatível como destino?** Não. **Versões compatíveis da API do Salesforce Commerce Cloud** v1. # Políticas que contêm as operações de API para criar e usar conexões O exemplo de política a seguir descreve as permissões da AWS necessárias para criar e usar conexões. Se você estiver criando um novo perfil, crie uma política que contenha o seguinte: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ É possível usar as seguintes políticas gerenciadas do IAM para permitir acesso: + [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole): concede acesso a recursos que vários processos do AWS Glue exigem para serem executados em seu nome. Esses recursos incluem o AWS Glue, Amazon S3, IAM, CloudWatch Logs e Amazon EC2. Se você seguir a convenção de nomenclatura para os recursos especificados nesta política, os processos do AWS Glue terão as permissões necessárias. Esta política geralmente é anexada a funções especificadas durante a definição de crawlers, trabalhos e endpoints de desenvolvimento. + [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess): concede acesso total aos recursos do AWS Glue quando uma identidade à qual a política está anexada usa o Console de Gerenciamento da AWS. Se você seguir a convenção de nomenclatura para os recursos especificados nesta política, os usuários poderão acessar todos os recursos do console. Esta política geralmente é anexada aos usuários do console do AWS Glue. # Configuração do Salesforce Commerce Cloud Antes de usar o AWS Glue para transferir dados do Salesforce Commerce Cloud, os seguintes requisitos deverão ser atendidos: ## Requisitos mínimos + Você tem uma aplicação cliente do Salesforce Commerce Cloud com clientId e clientSecret. + Sua conta do Salesforce Commerce Cloud está habilitada para acesso à API. Se você atender a esses requisitos, poderá conectar o AWS Glue à sua conta do Salesforce Commerce Cloud. Para conexões típicas, você não precisa fazer mais nada no Salesforce Commerce Cloud. # Configuração de conexões do Salesforce Commerce Cloud O Salesforce Commerce Cloud oferece suporte ao tipo de concessão CLIENT CREDENTIALS para OAuth2. + Esse tipo de concessão é considerado um OAuth 2.0 de “duas pernas”, pois é usado pelos clientes para obter um token de acesso fora do contexto de um usuário. O AWS Glue é capaz de usar o ID e o segredo do cliente para autenticar as APIs do Salesforce Commerce Cloud fornecidas pelos serviços personalizados que você definir. + Cada serviço personalizado é de propriedade de um usuário somente de API que tem um conjunto de perfis e permissões que autorizam o serviço a realizar ações específicas. Um token de acesso é associado a um único serviço personalizado. + Esse tipo de concessão resulta em um token de acesso de curta duração, que pode ser renovado com uma chamada a um endpoint de identidade. + Para obter mais informações sobre a documentação do Salesforce Commerce Cloud referente à geração das credenciais do cliente, consulte a [documentação do Salesforce](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html). Para configurar uma conexão do Salesforce Commerce Cloud: 1. No AWS Secrets Manager, crie um segredo com os detalhes a seguir. É necessário criar um segredo para cada conexão no AWS Glue. 1. Para uma aplicação conectada gerenciada pelo cliente, o segredo deve conter o segredo do consumidor da aplicação conectada com a chave USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET. 1. Em AWS Glue Studio, crie uma conexão em **Conexões de dados** seguindo estas etapas: 1. Em Conexões de dados, escolha **Criar conexão**. 1. Ao selecionar uma **Fonte de dados**, selecione o Salesforce Commerce Cloud. 1. Forneça seu **Código curto**, **ID da organização** e **ID do site** do Salesforce Commerce Cloud. 1. Selecione o URL do domínio do Salesforce Commerce Cloud da sua conta do Salesforce Commerce Cloud. 1. Selecione o perfil do IAM que o AWS Glue pode assumir e tem permissões para as seguintes ações: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. Forneça os escopos OAuth: opcional, o ClientId da aplicação cliente gerenciada pelo usuário do Salesforce Commerce Cloud ao qual deseja se conectar. 1. Selecione o `secretName` que você deseja usar para essa conexão no AWS Glue para colocar os tokens. 1. Selecione as opções de rede se quiser usar sua rede. 1. Conceda permissão ao perfil do IAM associado ao seu trabalho do AWS Glue para ler `secretName`. 1. Na configuração do trabalho do AWS Glue, forneça `connectionName` como uma **Conexão de rede adicional**. # Leitura de entidades do Salesforce Commerce Cloud **Pré-requisitos** + Um objeto do Salesforce Commerce Cloud do qual você deseja ler. Consulte a tabela de entidades compatíveis abaixo para verificar as entidades disponíveis. **Entidades compatíveis** | Entidade | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento | | --- | --- | --- | --- | --- | --- | | Atribuições | Sim | Sim | Sim | Sim | Sim | | Campanhas | Sim | Sim | Sim | Sim | Sim | | Catálogos | Sim | Sim | Sim | Sim | Sim | | Categorias | Sim | Sim | Sim | Sim | Sim | | Cupons | Sim | Sim | Sim | Sim | Sim | | Certificados de presente | Sim | Sim | Sim | Sim | Sim | | Produtos | Sim | Sim | Sim | Sim | Sim | | Promoções | Sim | Sim | Sim | Sim | Sim | | Grupos de código-fonte | Sim | Sim | Sim | Sim | Sim | **Exemplo** ``` salesforce_commerce_cloud_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforceCommerceCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "campaign", "API_VERSION": "v1" } ) ``` **Detalhes das entidades e dos campos do Salesforce Commerce Cloud** Lista de entidades: + Atribuições: [https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments]( https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments) + Campanhas: [https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns) + Catálogos: [https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs) + Categorias: [https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories) + Certificados de presente: [https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates) + Produtos: [https://developer.salesforce.com/docs/commerce/commerce-api/references/products](https://developer.salesforce.com/docs/commerce/commerce-api/references/products) + Promoções: [https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions) + Grupos de código-fonte: [https://developer.salesforce.com/docs/commerce/commerce-api/references/source-code-groups](https://developer.salesforce.com/docs/commerce/commerce-api/references/source-code-groups) **Particionamento de consultas** Podem ser fornecidas as opções adicionais do Spark `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND` e `NUM_PARTITIONS` se você quiser utilizar a simultaneidade no Spark. Com esses parâmetros, a consulta original seria dividida em `NUM_PARTITIONS` subconsultas, que poderiam ser executadas pelas tarefas do Spark simultaneamente. + `PARTITION_FIELD`: o nome do campo a ser usado para particionar a consulta. + `LOWER_BOUND`: um valor limite inferior inclusivo do campo de partição escolhido. Na data, aceitamos o formato de data do Spark usado em consultas SQL do Spark. Exemplo de valores válidos: `"2024-02-06"`. + `UPPER_BOUND`: um valor limite superior exclusivo do campo de partição escolhido. + `NUM_PARTITIONS`: número de partições. Os detalhes do suporte do campo de particionamento relativo às entidades são capturados na tabela abaixo: | Entidade | Campo de particionamento | DataType | | --- | --- | --- | | Campanhas | lastModified | DateTime | | Campanhas | startDate | DateTime | | Campanhas | endDate | DateTime | | Catálogos | creationDate | DateTime | | Categorias | creationDate | DateTime | | Certificados de presente | merchantId | String | | Certificados de presente | creationDate | DateTime | | Produtos | creationDate | DateTime | | Produtos | lastModified | DateTime | | Grupos de código-fonte | creationDate | DateTime | | Grupos de código-fonte | startTime | DateTime | | Grupos de código-fonte | endTime | DateTime | **Exemplo** ``` salesforceCommerceCloud_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforceCommerceCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "coupons", "API_VERSION": "v1", "PARTITION_FIELD": "creationDate", "LOWER_BOUND": "2020-05-01T20:55:02.000Z", "UPPER_BOUND": "2024-07-11T20:55:02.000Z", "NUM_PARTITIONS": "10" } ) ``` # Referência de opções de conexão do Salesforce Commerce Cloud Estas são as opções de conexão do Salesforce Commerce Cloud: + `ENTITY_NAME`(string): (obrigatório) usado para leitura. O nome do seu objeto no Salesforce Commerce Cloud. + `API_VERSION`(string): (obrigatório) usado para leitura/gravação. A versão da API Rest do Salesforce Commerce Cloud que você deseja usar. Exemplo: v1. + `SELECTED_FIELDS`(Lista): padrão: vazio(SELECIONE \$1). Usado para leitura. Colunas que deseja selecionar para o objeto. + `FILTER_PREDICATE`(string): padrão: vazio. Usado para leitura. Deve estar no formato Spark SQL. + `QUERY`(String): padrão: vazia. Usado para leitura. Consulta completa do Spark SQL. + `PARTITION_FIELD`(string): usado para leitura. Campo a ser usado para particionar a consulta. + `LOWER_BOUND`(string): usado para leitura. Um valor limite inferior inclusivo do campo de partição escolhido. + `UPPER_BOUND`(string): usado para leitura. Um valor limite superior exclusivo do campo de partição escolhido. + `NUM_PARTITIONS`(Inteiro): padrão: 1. Usado para leitura. Número de partições para leitura. # Limitações Estas são as limitações do conector do Salesforce Commerce Cloud: + O filtro Contém não está funcionando conforme o esperado durante o particionamento. + A entidade das zonas de CDN não oferece suporte a instâncias de sandbox e oferece suporte somente aos tipos de instância de desenvolvimento e produção. Para obter mais informações, consulte [https://help.salesforce.com/s/articleView?id=cc.b2c\$1embedded\$1cdn\$1overview.htm](https://help.salesforce.com/s/articleView?id=cc.b2c_embedded_cdn_overview.htm). + No Salesforce Commerce Cloud, não há um endpoint de API para buscar metadados dinâmicos. Como resultado, não há uma provisão para oferecer suporte aos campos personalizados nas entidades Produto e Categoria. + O ID do site é um parâmetro de consulta obrigatório. Você deve passar o valor do ID do site por meio da configuração de conector personalizado. Para obter mais informações, consulte [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html). + Você pode aplicar filtros em, no máximo, dois campos (exceto em níveis, se presentes) em uma única solicitação de API com a combinação de diferentes operadores, conforme mencionado na tabela abaixo: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html) + Em algumas entidades, o tipo de dados dos campos durante a recuperação é diferente de quando é usado como campos pesquisáveis. Como resultado, não há uma provisão para o recurso de filtro nesses campos. A tabela a seguir fornece detalhes sobre esses campos. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html)