# Conexão com o SAP OData
O SAP OData é um protocolo padrão da Web usado para consultar e atualizar dados presentes no SAP usando ABAP (Advanced Business Application Programming), aplicando e desenvolvendo tecnologias da Web, como HTTP, para fornecer acesso a informações de uma variedade de aplicações, plataformas e dispositivos externos. Com o produto, você pode acessar tudo de que precisa para ajudar na integração perfeita com o sistema, a aplicação ou dados SAP.
**Topics**
+ [Suporte do AWS Glue para SAP OData](sap-odata-support.md)
+ [Criar conexões](sap-odata-creating-connections.md)
+ [Criar um trabalho OData no SAP](sap-odata-creating-job.md)
+ [Escrever no SAP OData](sap-odata-writing.md)
+ [Uso do script de gerenciamento de estado do SAP OData](sap-odata-state-management-script.md)
+ [Particionamento para entidades não de ODP](sap-odata-non-odp-entities-partitioning.md)
+ [Opções de conexão do SAP OData](sap-odata-connection-options.md)
+ [Detalhes de entidades e campos OData do SAP](sap-odata-entity-field-details.md)
# Suporte do AWS Glue para SAP OData
O AWS Glue oferece suporte ao SAP OData da seguinte maneira:
**Compatível como fonte?**
Sim. Você pode usar trabalhos de ETL do AWS Glue para consultar dados do SAP OData.
**Compatível como destino?**
Sim. É possível usar trabalhos de ETL do AWS Glue para gravar registros no SAP OData.
**Versões compatíveis da API do SAP OData**
As seguintes versões da API do SAP OData são compatíveis:
+ 2.0
**Fontes compatíveis**
As seguintes fontes são compatíveis:
+ Fontes de ODP (Operational Data Provisioning):
+ Extratores BW (DataSources)
+ Visualizações do CDS
+ SLT
+ Fontes não de ODP, por exemplo:
+ Serviços de visualização do CDS
+ Serviços baseados em RFC
+ Serviços personalizados ABAP
**Componentes compatíveis do SAP**
São requisitos mínimos:
+ Você deve habilitar o serviço de catálogo para descoberta de serviços.
+ Configure fontes de dados de provisionamento de dados operacionais (ODP) para extração no SAP Gateway do seu sistema SAP.
+ **OData V2.0**: habilite os serviços de catálogo OData V2.0 no Gateway do SAP por meio da transação `/IWFND/MAINT_SERVICE`.
+ Habilite os serviços OData V2.0 no seu SAP Gateway por meio da transação `/IWFND/MAINT_SERVICE`.
+ O serviço SAP OData deve oferecer suporte às opções de paginação/consulta do lado do cliente, como `$top` e `$skip`. Ele também deve oferecer suporte à opção `$count` de consulta do sistema.
+ Você deve fornecer a autorização necessária para que o usuário no SAP descubra os serviços e extraia dados usando os serviços OData do SAP. Consulte a documentação de segurança fornecida pela SAP.
+ Se quiser usar o OAuth 2.0 como mecanismo de autorização, você deverá habilitar o OAuth 2.0 para o serviço OData e registrar o cliente OAuth de acordo com a documentação do SAP.
+ Para gerar um serviço OData com base em fontes de dados de ODP, o SAP Gateway Foundation deve ser instalado localmente em sua pilha de ERP/BW ou em uma configuração de hub.
+ Para as aplicações de ERP/BW, a pilha do NetWeaver AS ABAP do SAP deve ser da versão 7.50 SP02 ou superior.
+ Para o sistema de hub (SAP Gateway), o NetWeaver AS ABAP do SAP do sistema de hub deve ser da versão 7.50 SP01 ou superior para configuração de hub remoto.
+ Para fontes não de ODP, a versão da pilha do NetWeaver do SAP deve ser da versão 7.40 SP02 ou acima.
**Métodos de autenticação compatíveis**
Os seguintes métodos de autenticação são compatíveis:
+ Autenticação básica
+ OAuth 2.0
# Pré-requisitos
Antes de iniciar um trabalho do AWS Glue de extração de dados OData do SAP usando a conexão OData do SAP, atenda aos seguintes pré-requisitos:
+ O serviço OData relevante do SAP deve ser ativado no sistema SAP, garantindo que a fonte de dados esteja disponível para consumo. Se o serviço OData não estiver ativado, o trabalho do Glue não poderá acessar nem extrair dados do SAP.
+ Os mecanismos de autenticação apropriados, como autenticação básica (personalizada) ou o OAuth 2.0, devem ser configurados no SAP para garantir que o trabalho do AWS Glue possa estabelecer com sucesso uma conexão com o serviço OData do SAP.
+ Configure as políticas do IAM para conceder ao trabalho do AWS as permissões apropriadas para acessar o SAP, o Secrets Manager e outros recursos da AWS Glue envolvidos no processo.
+ Se o sistema SAP estiver hospedado em uma rede privada, a conectividade da VPC deverá ser configurada para garantir que o trabalho do AWS Glue possa se comunicar com o SAP de modo seguro, sem expor dados confidenciais pela internet pública.
O AWS Secrets Manager pode ser usado para armazenar de modo seguro informações confidenciais, como credenciais do SAP, que o trabalho do AWS Gluepode recuperar dinamicamente durante o runtime. Essa abordagem elimina a necessidade de codificar credenciais, aumentando a segurança e a flexibilidade.
Os pré-requisitos a seguir fornecem orientação passo a passo sobre como configurar cada componente para uma integração perfeita entre o AWS Glue e o OData do SAP.
**Topics**
+ [Ativação do OData do SAP](sap-odata-activation.md)
+ [Políticas do IAM](sap-odata-configuring-iam-permissions.md)
+ [Conectividade/conexão de VPC](sap-odata-connectivity-vpc-connection.md)
+ [Autenticação do SAP](sap-odata-authentication.md)
+ [AWS Secrets Manager para armazenar o segredo de autenticação](sap-odata-aws-secret-manager-auth-secret.md)
# Ativação do OData do SAP
Conclua as seguintes etapas para essa conexão OData do SAP:
## Fontes de ODP
Para transferir dados de um provedor ODP, é necessário atender aos seguintes requisitos:
+ Você tem uma instância do NetWeaver AS ABAP do SAP.
+ Sua instância do NetWeaver do SAP contém um provedor ODP do qual você deseja transferir dados. Os provedores ODP incluem:
+ DataSources do SAP (código de transação RSO2)
+ Visualizações dos CDS ABAP do ABAP Core Data Services
+ Sistemas BW ou BW/4HANA do SAP (InfoObject, DataStore Object)
+ Replicação em tempo real de tabelas e visualizações de BD do SAP Source System via SAP Landscape Replication Server (SAP SLT)
+ Visualizações de informações de HANA do SAP em fontes baseadas em ABAP do SAP
+ Sua instância do NetWeaver do SAP tem o componente SAP Gateway Foundation.
+ Você criou um serviço OData que extrai dados do seu provedor ODP. Para criar o serviço OData, você usa o desenvolvedor de serviço de gateway do SAP. Para acessar os dados do ODP, o Amazon AppFlow chama esse serviço usando a API OData. Para obter mais informações, consulte [Generating a Service for Extracting ODP Data via OData](https://help.sap.com/docs/SAP_BPC_VERSION_BW4HANA/dd104a87ab9249968e6279e61378ff66/69b481859ef34bab9cc7d449e6fff7b6.html?version=11.0) na documentação de BW/4HANA do SAP.
+ Para gerar um serviço OData com base em fontes de dados de ODP, o SAP Gateway Foundation deve ser instalado localmente em sua pilha de ERP/BW ou em uma configuração de hub.
+ Para as aplicações de ERP/BW, a pilha do NetWeaver AS ABAP do SAP deve ser da versão 7.50 SP02 ou superior.
+ Para o sistema de hub (SAP Gateway), o NetWeaver AS ABAP do SAP do sistema de hub deve ser da versão 7.50 SP01 ou superior para configuração de hub remoto.
## Fontes não de ODP
+ A versão da pilha do SAP NetWeaver deve ser 7.40 SP02 ou superior.
+ Você deve habilitar o serviço de catálogo para descoberta de serviços.
+ **OData V2.0**: Os serviços de catálogo OData V2.0 podem ser habilitados no Gateway do SAP por meio da transação `/IWFND/MAINT_SERVICE`
+ O serviço SAP OData deve oferecer suporte às opções de paginação/consulta do lado do cliente, como `$top` e `$skip`. Ele também deve oferecer suporte à opção `$count` de consulta do sistema.
+ Para o OAuth 2.0, vVocê deve habilitar o OAuth 2.0 para o serviço OData e registrar o cliente de OAuth de acordo com a documentação do SAP, e definir a URL de redirecionamento autorizada da seguinte maneira:
+ `https://.console.aws.amazon.com/gluestudio/oauth`, substituindo `` pela região em que o AWS Glue está sendo executado, por exemplo: us-east-1.
+ Você deve habilitar a configuração segura para conexão por HTTPS.
+ Você deve fornecer a autorização necessária para que o usuário no SAP descubra os serviços e extraia dados usando os serviços OData do SAP. Consulte a documentação de segurança fornecida pela SAP.
# Políticas do IAM
## 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 necessárias do AWS IAM 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": "*"
},
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue"
],
"Resource": "*"
}
]
}
```
------
O perfil deve conceder acesso a todos os recursos usados pelo trabalho, por exemplo, o Amazon S3. Se você não quiser usar o método acima, como alternativa use as seguintes políticas gerenciadas do IAM.
+ [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 fazer a execução 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.
+ [SecretsManagerReadWrite](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/SecretsManagerReadWrite): fornece acesso de leitura/gravação ao AWS Secrets Manager pelo Console de Gerenciamento da AWS. Observação: isso exclui ações do IAM. Portanto, combine com o `IAMFullAccess` se for necessária configuração de rotação.
**Políticas/permissões do IAM necessárias para configurar a VPC**
As seguintes permissões do IAM são necessárias ao usar a conexão de VPC para criar a conexão do AWS Glue. Para obter mais detalhes, consulte [Criar uma política do IAM para o AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/create-service-policy.html).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"*"
]
}
]
}
```
------
# Conectividade/conexão de VPC
Etapas para a conexão de VPC:
1. Use a conexão de VPC existente ou crie uma nova conexão seguindo a [documentação da Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html).
1. Certifique-se de ter um gateway NAT que direcione o tráfego para a Internet.
1. Escolha o endpoint da VPC como o gateway do Amazon S3 para criar uma conexão.
1. Habilite a resolução do DNS e o nome do host do DNS para usar os serviços de DNS fornecidos pela AWS.
1. Acesse a VPC criada e adicione os endpoints necessários para os diferentes serviços, como STS, AWS Glue, Secret Managers.
1. Escolha Criar endpoint.
1. Em Categoria do serviço, selecione Serviços da AWS.
1. Em Nome do serviço, escolha o serviço ao qual você está se conectando.
1. Escolha a VPC e Habilitar nome do DNS.
1. Endpoints da VPC necessários para a conexão da VPC:
1. [STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sts_vpc_endpoint_create.html)
1. [AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/vpc-interface-endpoints.html)
1. [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)
## Configuração do security group
O grupo de segurança deve permitir tráfego da VPC do AWS Glue para a porta de escuta para que o AWS Glue possa se conectar a ela. É uma prática recomendada restringir o intervalo de endereços IP de origem o máximo possível.
O AWS Glue exige um grupo de segurança especial que permite todo o tráfego de entrada originado nele mesmo. Você pode criar uma regra autorreferenciada que permita todo o tráfego originado no grupo de segurança. Você pode modificar um grupo de segurança existente e especificá-lo como origem.
Abra a comunicação das portas HTTPS do endpoint da URL (instância NLB ou SAP).
## Opções de conectividade
+ Conexão HTTPS com NLB interno e externo, certificado SSL da autoridade de certificação (CA), certificado SSL não autoassinado
+ Conexão HTTPS com instância do SAP, certificado SSL de autoridade certificadora (CA), certificado SSL não auto-assinado
# Autenticação do SAP
O conector do SAP é compatível com os métodos de autenticação CUSTOM (essa é a autenticação BASIC do SAP) e OAUTH.
## Autenticação personalizada
O AWS Glue é compatível com Custom (autenticação básica) como um método para estabelecer conexões com os sistemas SAP, permitindo o uso de um nome de usuário e senha para acesso seguro. Esse tipo de autorização: funciona bem em cenários de automação, pois permite o uso do nome de usuário e senha antecipadamente com as permissões de um usuário específico na instância OData do SAP. O AWS Glue pode usar o nome de usuário e senha para autenticar as APIs OData do SAP. No AWS Glue, a autorização básica é implementada como autorização personalizada.
Para obter a documentação pública do SAP OData para o fluxo de autenticação básica, consulte [HTTP Basic Authentication](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b/5c8bca0af1654b05a83193b2922dcee2.html).
## Autenticação OAuth 2.0
O AWS Glue também é compatível com o OAuth 2.0 como um mecanismo de autenticação seguro para estabelecer conexões com seus sistemas SAP. Isso permite uma integração perfeita, garantindo a conformidade com os padrões modernos de autenticação e aprimorando a segurança do acesso aos dados.
## Tipo de concessão AUTHORIZATION\$1CODE
O tipo de concessão determina como o AWS Glue se comunica com o SAP OData para solicitar acesso aos seus dados. O SAP OData só oferece suporte ao tipo de concessão `AUTHORIZATION_CODE`. Esse tipo de concessão é considerado um OAuth de “três pernas”, pois conta com o redirecionamento dos usuários para o servidor de autorização de terceiros para autenticar o usuário. É usado ao criar conexões por meio do console do AWS Glue.
Os usuários ainda podem optar por criar a própria aplicação conectada no SAP OData e fornecer ID e segredo do cliente próprios ao criar conexões por meio do console do AWS Glue. Nesse cenário, eles ainda serão redirecionados para o SAP OData para fazer login e autorizar o acesso do AWS Glue aos recursos.
Esse tipo de concessão resulta em um token de atualização e um token de acesso. O token de acesso tem vida curta e pode ser atualizado automaticamente sem a interação do usuário usando o token de atualização.
Para obter documentação pública do SAP OData sobre como criar uma aplicação conectada para o fluxo de código de autorização do OAuth, consulte [Autenticação usando o OAuth 2.0](https://help.sap.com/docs/ABAP_PLATFORM_NEW/e815bb97839a4d83be6c4fca48ee5777/2e5104fd87ff452b9acb247bd02b9f9e.html).
# AWS Secrets Manager para armazenar o segredo de autenticação
Você precisará armazenar os segredos da conexão OData do SAP no AWSSecrets Manager, configurar as permissões necessárias para recuperação conforme especificado na seção [Políticas do IAM](sap-odata-configuring-iam-permissions.md) e usá-las ao criar uma conexão.
Use o AWS Management Console do AWS Secrets Manager para criar um segredo para a sua fonte no SAP. Para obter mais informações, consulte [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html). Os detalhes do AWS Secrets Manager devem incluir os elementos de código a seguir.
## Serviço de autenticação personalizada
Você precisará inserir o nome de usuário do sistema SAP no lugar de ** e sua senha no lugar de ** e True ou False. Nesse contexto, configurar `basicAuthDisableSSO` como `true` desabilita a autenticação única (SSO) para solicitações de Autenticação Básica, exigindo credenciais de usuário explícitas para cada solicitação. Por outro lado, configurar esse valor como `false` permite o uso de sessões de SSO existentes, se disponíveis.
```
{
"basicAuthUsername": "",
"basicAuthPassword": "",
"basicAuthDisableSSO": "",
"customAuthenticationType": "CustomBasicAuth"
}
```
## Segredo do OAuth 2.0
Caso você esteja usando o OAuth 2.0 como mecanismo de autenticação, o segredo no AWS Secrets Manager deve ter o **ClientId da aplicação cliente gerenciado pelo usuário** no formato a seguir. Você precisará inserir o segredo do cliente SAP no lugar de .
```
{"USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET": ""
}
```
# Criar conexões
Para configurar uma conexão OData no SAP:
1. Faça login no Console de gerenciamento da AWS e abra o [console do AWS Glue](https://console.aws.amazon.com/glue). No AWS Glue Studio, crie uma conexão seguindo as etapas abaixo:
1. Clique em Conexões de dados no painel esquerdo.
1. Clique em Criar conexão.
1. Selecione **OData do SAP** em **Escolher fonte de dados**
1. Forneça o URL do **host da aplicação da instância** do SAP OData à qual você deseja se conectar. Essa URL do host da aplicação deve pode ser acessada pela Internet pública para conexões que não sejam de VPC.
1. Forneça o **Caminho do serviço da aplicação** da instância do SAP OData à qual você deseja se conectar. Esse é o mesmo caminho do serviço de catálogo. Por exemplo: `/sap/opu/odata/iwfnd/catalogservice;v=2`. O AWS Glue não aceita um caminho de objeto específico.
1. Forneça o **Número do cliente** da instância do SAP OData à qual você deseja se conectar. Os valores aceitáveis são [001 a 999]. Exemplo: 010
1. Forneça o **Número da porta** da instância do SAP OData à qual você deseja se conectar. Exemplo: 443
1. Forneça o **Idioma de logon** da instância do SAP OData à qual você deseja se conectar. Exemplo: PT\$1BR
1. Selecione o perfil do AWS IAM que o AWS Glue pode assumir e tem permissões, conforme descrito na seção [Políticas do IAM](sap-odata-configuring-iam-permissions.md).
1. Selecione o **Tipo de autenticação** que você deseja usar para essa conexão no AWS Glue, na lista suspensa OAUTH2 ou CUSTOM
1. CUSTOM: selecione o segredo que você criou conforme especificado na seção [AWS Secrets Manager para armazenar o segredo de autenticação](sap-odata-aws-secret-manager-auth-secret.md).
1. OAUTH 2.0: insira as seguintes entradas apenas no caso do OAuth 2.0:
1. Em **ClientId da aplicação cliente gerenciado pelo usuário**, insira o ID do cliente.
1. `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` (o segredo do cliente) no AWS Secrets Manager que você criou na seção [AWS Secrets Manager para armazenar o segredo de autenticação](sap-odata-aws-secret-manager-auth-secret.md).
1. Em **URL do código de autorização**, insira a URL do código de autorização.
1. Em **URL dos tokens de autorização**, insira a URL dos tokens de autorização.
1. Em **Escopos do OAuth**, insira os escopos do OAuth separados por espaços. Exemplo: `/IWFND/SG_MED_CATALOG_0002 ZAPI_SALES_ORDER_SRV_0001`
1. Selecione as opções de rede se quiser usar sua rede. Consulte mais detalhes em [Conectividade/conexão de VPC](sap-odata-connectivity-vpc-connection.md).
1. Conceda permissão ao perfil do IAM associado ao seu trabalho do AWS Glue para ler `secretName`. Para obter mais detalhes, consulte [Políticas do IAM](sap-odata-configuring-iam-permissions.md).
1. Escolha **Testar conexão** e teste sua conexão. Se o teste de conexão for bem-sucedido, clique em Avançar, insira o nome da conexão e salve-a. A funcionalidade de teste de conexão não está disponível se você tiver escolhido Opções de rede (VPC).
# Criar um trabalho OData no SAP
Consulte [Criar trabalhos de ETL visuais com o AWS Glue Studio](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html)
# Fontes de Provisionamento de Dados Operacionais (ODP)
O Provisionamento de Dados Operacionais (ODP) oferece uma infraestrutura técnica que você pode usar para dar suporte à extração e à replicação de dados para várias aplicações de destino e que é compatível com mecanismos delta nesses cenários. No caso de um procedimento delta, os dados de uma fonte (Provedor ODP) são automaticamente gravados em uma fila delta (Fila Delta Operacional, ODQ) usando um processo de atualização ou passados para a fila delta usando uma interface de extração. Um provedor ODP pode ser um DataSource (extratores), visualizações do ABAP Core Data Services (Visualizações do ABAP CDS), SAP BW ou SAP BW/4HANA, SAP Landscape Transformation Replication Server (SLT) e SAP HANA Information Views (visualizações de cálculo). As aplicações de destino (chamados de "assinantes" de ODQ ou, mais geralmente, "Consumidores de ODP") recuperam os dados da fila delta e continuam processando esses dados.
## Carga total
No contexto das entidades OData e ODP do SAP, uma **carga total** se refere ao processo de extrair todos os dados disponíveis de uma entidade ODP em uma única operação. Essa operação recupera todo o conjunto de dados do sistema de origem, garantindo que o sistema de destino tenha uma cópia abrangente e atualizada dos dados da entidade. As cargas totais geralmente são usadas para fontes que não são compatíveis com cargas incrementais ou quando é necessária uma atualização do sistema de destino.
**Exemplo**
Você pode definir explicitamente o sinalizador `ENABLE_CDC` como false ao criar o DynamicFrame. Observação: `ENABLE_CDC` é false por padrão. Se você não quiser inicializar a fila delta, não precisará enviar esse sinalizador nem defini-lo como true. Não definir esse sinalizador como true resultará na extração da carga total.
```
sapodata_df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "false"
}, transformation_ctx=key)
```
## Carga incremental
Uma **carga incremental** no contexto das entidades ODP (Operational Data Provisioning) envolve a extração somente dos dados novos ou alterados (deltas) do sistema de origem desde a última extração de dados, evitando o pré-processamento dos registros já processados. Essa abordagem melhora significativamente a eficiência, reduz os volumes de transferência de dados, melhora a performanda, garante a sincronização entre os sistemas e minimiza o tempo de processamento, especialmente para grandes conjuntos de dados que mudam com frequência.
# Transferências incrementais baseadas no token delta
Para habilitar a transferência incremental usando Change Data Capture (CDC) para entidades habilitadas para ODP compatíveis, siga estas etapas:
1. Crie a tarefa de transferência incremental no modo de script.
1. Ao criar o DataFrame ou o DynamicFrame do Glue, você precisa passar a opção `"ENABLE_CDC": "True"`. Essa opção garante que você receberá um token delta da SAP, que poderá ser usado para subsequente recuperação dos dados alterados.
O token delta poderá ser encontrado na última linha do dataframe, na coluna DELTA\$1TOKEN. Você poderá usar esse token como uma opção de conector em chamadas subsequentes para recuperar o próximo conjunto de dados incrementalmente.
**Exemplo**
+ Definimos o sinalizador `ENABLE_CDC` como `true`, ao criar o DynamicFrame. Observação: `ENABLE_CDC` será `false` por padrão, se você não quiser inicializar a fila delta, não precisará enviar esse sinalizador nem defini-lo como true. Não definir esse sinalizador como true resultará na extração da carga total.
```
sapodata_df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "true"
}, transformation_ctx=key)
# Extract the delta token from the last row of the DELTA_TOKEN column
delta_token_1 = your_logic_to_extract_delta_token(sapodata_df) # e.g., D20241029164449_000370000
```
+ O token delta extraído pode ser passado como uma opção para recuperar novos eventos.
```
sapodata_df_2 = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
// passing the delta token retrieved in the last run
"DELTA_TOKEN": delta_token_1
} , transformation_ctx=key)
# Extract the new delta token for the next run
delta_token_2 = your_logic_to_extract_delta_token(sapodata_df_2)
```
Observe que o último registro, no qual o `DELTA_TOKEN` está presente, não é um registro transacional da fonte e existe apenas com a finalidade de passar o valor do token delta.
Além do `DELTA_TOKEN`, os campos a seguir são retornados em cada linha do dataframe.
+ **GLUE\$1FETCH\$1SQ**: esse é um campo sequencial, gerado a partir do timestamp EPOC na ordem de recebimento dos registros e é exclusivo para cada registro. Isso pode ser usado se você precisar conhecer ou estabelecer a ordem das alterações no sistema de origem. Esse campo estará presente apenas para entidades habilitadas para ODP.
+ **DML\$1STATUS**: isso exibirá `UPDATED` para todos os registros recém-inseridos e atualizados a partir da fonte e `DELETED` para os registros que foram excluídos da fonte.
Para obter mais detalhes sobre como gerenciar estado e reutilizar o token delta para recuperar registros alterados por meio de um exemplo, consulte a seção [Uso do script de gerenciamento de estado do SAP OData](sap-odata-state-management-script.md).
## Invalidação do token delta
Um token delta é associado ao conjunto de serviços e a um usuário. Se uma extração inicial com `“ENABLE_CDC” : “true”` for iniciada para o mesmo conjunto de serviços e usuário, todos os tokens delta anteriores emitidos como resultado de uma inicialização anterior serão invalidados pelo serviço OData do SAP. Invocar o conector com um token delta expirado gerará uma exceção:
`Could not open data access via extraction API RODPS_REPL_ODP_OPEN`
# Serviços OData (fontes não ODP)
## Carga total
Para sistemas não ODP (Operational Data Provisioning), uma **carga total** envolve extrair todo o conjunto de dados do sistema de origem e carregá-lo no sistema de destino. Como os sistemas não ODP não são inerantemente compatíveis com mecanismos avançados de extração de dados como deltas, o processo é simples, mas pode consumir muitos recursos, dependendo do tamanho dos dados.
## Carga incremental
Para sistemas ou entidades que não são compatíveis com **ODP (Operational Data Provisioning)**, a transferência incremental de dados pode ser gerenciada manualmente por meio da implementação de um mecanismo baseado em timestamp para rastrear e extrair as alterações.
**Transferências incrementais baseadas em timestamp**
Para entidades não habilitadas para ODP (ou para entidades habilitadas para ODP que não usam o sinalizador ENABLE\$1CDC), você pode usar uma opção `filteringExpression` no conector para indicar o intervalo de `datetime` para o qual queremos recuperar dados. Esse método depende de um campo de timestamp nos dados, que mostra quando cada registro foi criado/modificado a última vez.
**Exemplo**
Recuperação de registros que foram alterados após 2024-01-01T00:00:00.000
```
sapodata_df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"filteringExpression": "LastChangeDateTime >= 2024-01-01T00:00:00.000"
}, transformation_ctx=key)
```
Nesse exemplo, `LastChangeDateTime` é o campo que representa quando cada registro foi modificado a última vez. O nome real do campo pode variar, dependendo da entidade específica do SAP OData.
Para obter um novo subconjunto de dados em execuções subsequentes, você pode atualizar o `filteringExpression` com um novo carimbo de data e hora. Normalmente, esse seria o valor máximo do carimbo de data e hora dos dados recuperados anteriormente.
**Exemplo**
```
max_timestamp = get_max_timestamp(sapodata_df) # Function to get the max timestamp from the previous run
next_filtering_expression = f"LastChangeDateTime > {max_timestamp}"
# Use this next_filtering_expression in your next run
```
Na próxima seção, forneceremos uma abordagem automatizada para gerenciar essas transferências incrementais com base em carimbo de data e hora, eliminando a necessidade de atualizar manualmente a expressão de filtragem entre as execuções.
# Escrever no SAP OData
Esta seção descreve como gravar dados em seu serviço SAP OData usando o conector AWS Glue para SAP OData.
**Pré-requisitos**
+ Acessar um serviço SAP OData
+ Um objeto EntitySet do SAP OData em que você gostaria de escrever. Você precisará do nome do objeto.
+ Credenciais válidas do SAP OData e uma conexão válida
+ Permissões apropriadas, conforme descrito nas [políticas do IAM](https://docs.aws.amazon.com/glue/latest/dg/sap-odata-configuring-iam-permissions.html)
O conector do SAP OData oferece suporte duas operações de escrita:
+ INSERT
+ UPDATE
Ao usar a operação de escrita UPDATE, ID\$1FIELD\$1NAMES deve ser fornecido para especificar o campo de ID externo para os registros.
**Exemplo:**
```
sapodata_write = glueContext.write_dynamic_frame.from_options(
frame=frameToWrite,
connection_type="sapodata",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"WRITE_OPERATION": "INSERT"
}
```
# Uso do script de gerenciamento de estado do SAP OData
Para usar o script de gerenciamento de estado OData do SAP no trabalho do AWS Glue, siga estas etapas:
+ Faça o download do script de gerenciamento de estado `s3://aws-blogs-artifacts-public/artifacts/BDB-4789/sap_odata_state_management.zip ` no bucket público do Amazon S3.
+ Carregue o script em um bucket do Amazon S3 que seu trabalho do AWS Glue tenha permissões para acessar.
+ Referencie o script no ttrabalho do AWS Glue: quando criar ou atualizar o trabalho do AWS Glue, passe a opção `'--extra-py-files'` referenciando o caminho do script no bucket do Amazon S3. Por exemplo: `--extra-py-files s3://your-bucket/path/to/sap_odata_state_management.py`
+ Importe e use a biblioteca de gerenciamento de estado nos scripts do trabalho do AWS Glue.
## Exemplo de transferência incremental baseada no token delta
Veja um exemplo de como usar o script de gerenciamento de estado para transferências incrementais com base em tokens delta:
```
from sap_odata_state_management import StateManagerFactory, StateManagerType, StateType
# Initialize the state manager
state_manager = StateManagerFactory.create_manager(
manager_type=StateManagerType.JOB_TAG,
state_type=StateType.DELTA_TOKEN,
options={
"job_name": args['JOB_NAME'],
"logger": logger
}
)
# Get connector options (including delta token if available)
key = "SAPODataNode"
connector_options = state_manager.get_connector_options(key)
# Use the connector options in your Glue job
df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "true",
**connector_options
}
)
# Process your data here...
# Update the state after processing
state_manager.update_state(key, sapodata_df.toDF())
```
## Exemplo de transferência incremental baseada no timestamp
Veja um exemplo de como usar o script de gerenciamento de estado para transferências incrementais com base em tokens delta:
```
from sap_odata_state_management import StateManagerFactory, StateManagerType, StateType
# Initialize the state manager
state_manager = StateManagerFactory.create_manager(
manager_type=StateManagerType.JOB_TAG,
state_type=StateType.DELTA_TOKEN,
options={
"job_name": args['JOB_NAME'],
"logger": logger
}
)
# Get connector options (including delta token if available)
key = "SAPODataNode"
connector_options = state_manager.get_connector_options(key)
# Use the connector options in your Glue job
df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "true",
**connector_options
}
)
# Process your data here...
# Update the state after processing
state_manager.update_state(key, sapodata_df.toDF())
```
Nos dois exemplos, o script de gerenciamento de estado lida com as complexidades de armazenar o estado (token delta ou carimbo de data e hora) entre as execuções do trabalho. Ele recupera automaticamente o último estado conhecido ao obter as opções do conector e atualiza o estado após o processamento, garantindo que cada execução de trabalho só processe dados novos ou alterados.
# Particionamento para entidades não de ODP
No Apache Spark, particionamento se refere ao modo como os dados são divididos e distribuídos entre os nós de trabalho de um cluster para processamento paralelo. Cada partição é um bloco lógico de dados que pode ser processado de modo independente por uma tarefa. Particionamento é um conceito fundamental no Spark que afeta diretamente a performance, a escalabilidade e a utilização de recursos. Os trabalhos do AWS Glue usam o mecanismo de particionamento do Spark para dividir o conjunto de dados em partes menores (partições) que podem ser processadas paralelamente nos nós de trabalho do cluster. Observe que o particionamento não é aplicável a entidades de ODP.
Para obter mais detalhes, consulte [AWS Glue Spark and PySpark jobs](https://docs.aws.amazon.com/glue/latest/dg/spark_and_pyspark.html).
**Pré-requisitos**
Um objeto OData do SAP que você deseja ler. Você precisará do nome do objeto/EntitySet. Por exemplo: ` /sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder `.
**Exemplo**
```
sapodata_read = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "/sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder"
}, transformation_ctx=key)
```
## Particionamento de consultas
### Particionamento baseado no campo
É possível fornecer as opções adicionais do Spark `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND` e `NUM_PARTITIONS` se 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. Os campos Integer, Date e DateTime oferecem suporte ao particionamento com base em campo no conector do SAP OData.
+ `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.
Em qualquer campo com dados do tipo DataTime, o formato de timestamp do Spark usado nas consultas em SQL do Spark é aceito.
Exemplos de valores válidos: `"2000-01-01T00:00:00.000Z"`
+ `UPPER_BOUND`: um valor limite superior exclusivo do campo de partição escolhido.
+ `NUM_PARTITIONS`: número de partições.
+ `PARTITION_BY`: o tipo de particionamento a ser realizado, `FIELD` a ser passado no caso de particionamento baseado em campo.
**Exemplo**
```
sapodata= glueContext.create_dynamic_frame.from_options(
connection_type="sapodata",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "/sap/opu/odata/sap/SEPM_HCM_SCENARIO_SRV/EmployeeSet",
"PARTITION_FIELD": "validStartDate"
"LOWER_BOUND": "2000-01-01T00:00:00.000Z"
"UPPER_BOUND": "2020-01-01T00:00:00.000Z"
"NUM_PARTITIONS": "10",
"PARTITION_BY": "FIELD"
}, transformation_ctx=key)
```
### Particionamento baseado em registro
A consulta original seria dividida em `NUM_PARTITIONS` subconsultas, que poderiam ser executadas pelas tarefas do Spark simultaneamente.
O particionamento com base em registros só é compatível para entidades não ODP, pois a paginação em entidades ODP é compatível por meio do próximo token/ignorar token.
+ `PARTITION_BY`: o tipo de particionamento a ser executado. `COUNT` deve ser passado no caso de particionamento baseado em registro.
**Exemplo**
```
sapodata= glueContext.create_dynamic_frame.from_options(
connection_type="sapodata",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "/sap/opu/odata/sap/SEPM_HCM_SCENARIO_SRV/EmployeeSet",
"NUM_PARTITIONS": "10",
"PARTITION_BY": "COUNT"
}, transformation_ctx=key)
```
# Limitações/legendas
+ As entidades de ODP não são compatíveis com particionamento baseado em registro, pois a paginação é feita usando o token skip/token delta. Assim sendo, para o particionamento baseados em registros, o valor padrão de maxConcurrency é definido como “null”, independentemente da entrada do usuário.
+ Quando tanto limite quanto partição são aplicados, o limite tem precedência sobre a partição.
# Opções de conexão do SAP OData
Estas são as opções de conexão do SAP OData:
+ `ENTITY_NAME`(string): (obrigatório) usado para leitura. O nome do seu objeto no SAP OData.
Por exemplo: /sap/opu/odata/sap/API\$1SALES\$1ORDER\$1SRV/A\$1SalesOrder
+ `API_VERSION` (String): (Opcional) usado para leitura. Versão da API Rest do SAP OData que você deseja usar. Exemplo: 2.0.
+ `SELECTED_FIELDS`(Lista): padrão: vazio(SELECIONE \$1). Usado para leitura. Colunas que deseja selecionar para o objeto.
Por exemplo: SalesOrder
+ `FILTER_PREDICATE`(string): padrão: vazio. Usado para leitura. Deve estar no formato Spark SQL.
Por exemplo: `SalesOrder = "10"`
+ `QUERY`(string): padrão: vazio. Usado para leitura. Consulta completa do Spark SQL.
Por exemplo: `SELECT * FROM /sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder`
+ `PARTITION_FIELD`(string): usado para leitura. Campo a ser usado para particionar a consulta.
Por exemplo: `ValidStartDate`
+ `LOWER_BOUND`(string): usado para leitura. Um valor limite inferior inclusivo do campo de partição escolhido.
Por exemplo: `"2000-01-01T00:00:00.000Z"`
+ `UPPER_BOUND`(string): usado para leitura. Um valor limite superior exclusivo do campo de partição escolhido.
Por exemplo: `"2024-01-01T00:00:00.000Z"`
+ `NUM_PARTITIONS`(Inteiro): padrão: 1. Usado para leitura. Número de partições para leitura.
+ `INSTANCE_URL` (String): o URL do host da aplicação da instância do SAP.
Por exemplo: `https://example-externaldata.sierra.aws.dev`
+ `SERVICE_PATH` (String): o caminho do serviço da aplicação da instância do SAP.
Por exemplo: `/sap/opu/odata/iwfnd/catalogservice;v=2`
+ `CLIENT_NUMBER` (String): o número do cliente da aplicação da instância do SAP.
Por exemplo: 100
+ `PORT_NUMBER` (String): padrão: o número da porta da aplicação da instância do SAP.
Por exemplo: 443
+ `LOGON_LANGUAGE` (String): o idioma de logon da aplicação da instância do SAP.
Por exemplo: `EN`
+ `ENABLE_CDC` (String): define se deve ser executado um trabalho com a captura de dados de alteração (CDC) habilitada, ou seja, com alterações de faixa.
Por exemplo: `True/False`
+ `DELTA_TOKEN` (String): executa uma extração de dados incremental com base no token Delta válido fornecido.
Por exemplo: `D20241107043437_000463000`
+ `PAGE_SIZE` (inteiro): define o tamanho da página para consultar os registros. O tamanho de página padrão é 50.000. Quando um tamanho de página é especificado, o SAP retorna apenas o número definido de registros por chamada de API, em vez de todo o conjunto de dados. O conector fornecerá também o número total de registros e processará a paginação usando o tamanho de página especificado. Se você precisar de um tamanho de página maior, poderá escolher qualquer valor até 500.000, que é o máximo permitido. Qualquer tamanho de página especificado que exceda 500.000 será ignorado. Em vez disso, o sistema usará o tamanho máximo de página permitido. Você pode especificar o tamanho da página na interface de usuário do AWS Glue Studioadicionando uma opção de conexão `PAGE_SIZE` com o valor desejado.
Por exemplo: `20000`
# Detalhes de entidades e campos OData do SAP
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/sap-odata-entity-field-details.html)