# Conexão com o QuickBooks O QuickBooks é uma aplicação de contabilidade líder para pequenas e médias empresas. As aplicações de contabilidade do QuickBooks datam da década de 1980 como um dos primeiros produtos da Intuit e, consequentemente, eram originalmente um software de desktop. Hoje, o QuickBooks oferece várias aplicações contábeis e financeiras empresariais como software instalável e software SaaS baseado em nuvem. Como usuário do QuickBooks, é possível conectar o AWS Glue à sua conta do QuickBooks. Em seguida, será possível usar o QuickBooks como fonte de dados nos seus trabalhos de ETL. Execute esses trabalhos para transferir dados entre o QuickBooks e serviços da AWS ou outras aplicações com suporte. **Topics** + [Suporte do AWS Glue para QuickBooks](quickbooks-support.md) + [Políticas que contêm as operações de API para criar e usar conexões](quickbooks-configuring-iam-permissions.md) + [Configuração do QuickBooks](quickbooks-configuring.md) + [Configuração de conexões do QuickBooks](quickbooks-configuring-connections.md) + [Leitura de entidades do QuickBooks](quickbooks-reading-from-entities.md) + [Opções de conexão do QuickBooks](quickbooks-connection-options.md) + [Limitações e notas do conector do QuickBooks](quickbooks-connector-limitations.md) # Suporte do AWS Glue para QuickBooks O AWS Glue oferece suporte ao QuickBooks da seguinte forma: **Compatível como fonte?** Sim. É possível usar trabalhos de ETL do AWS Glue para consultar dados do QuickBooks. **Compatível como destino?** Nº **Versões da API do QuickBooks com suporte** Versões da API do QuickBooks com suporte: + v3 # 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": "*" } ] } ``` ------ Se você não quiser usar o método acima, como alternativa use as seguintes políticas do IAM gerenciadas: + [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. # Configuração do QuickBooks Antes de poder usar o AWS Glue para transferir dados do QuickBooks, os seguintes requisitos deverão ser atendidos: ## Requisitos mínimos Estes são os requisitos mínimos: + Você tem uma conta do QuickBooks. + Sua conta do QuickBooks precisa estar habilitada para acesso à API. Para obter mais informações, consulte os seguintes tópicos na documentação do QuickBooks: + [Criar uma conta do Intuit](https://quickbooks.intuit.com/learn-support/en-us/help-article/account-management/create-intuit-user-account/L62kSFEOM_US_en_US) + [Criar e começar a desenvolver sua aplicação](https://developer.intuit.com/app/developer/qbo/docs/get-started/start-developing-your-app) Se você atender a esses requisitos, poderá conectar o AWS Glue à sua conta do QuickBooks. Para conexões típicas, você não precisa fazer mais nada no QuickBooks. # Configuração de conexões do QuickBooks O QuickBooks oferece suporte ao tipo de concessão AUTHORIZATION\$1CODE para OAuth2. O tipo de concessão determina como o AWS Glue se comunica com o QuickBooks para solicitar acesso aos seus dados. + Esse tipo de concessão é considerado um OAuth de “três pernas”, pois conta com o redirecionamento dos usuários para um 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 sua própria aplicação conectada no QuickBooks e fornecer seus próprios ID e segredo do cliente ao criar conexões por meio do console do AWS Glue. Nesse cenário, eles ainda serão redirecionados para o QuickBooks 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 a documentação pública do QuickBooks sobre como criar uma aplicação conectada para o fluxo de código de autorização do OAuth, consulte [Configuração do OAuth 2.0](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0). Para configurar uma conexão do QuickBooks: 1. No AWS Glue Glue Studio, crie uma conexão em **Conexões de dados** seguindo estas etapas: 1. Ao selecionar um **Tipo de conexão**, escolha QuickBooks. 1. Forneça o URL da instância e o ID da instância do QuickBooks com a qual deseja se conectar. 1. Selecione o perfil do AWS 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. 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`. # Leitura de entidades do QuickBooks **Pré-requisito** Um objeto do QuickBooks do qual você deseja ler. **Entidades compatíveis quanto à origem**: | Entidade | Pode ser filtrada | Oferece suporte a limite | Oferece suporte a Ordenar por | Oferece suporte a Selecionar \$1 | Oferece suporte a particionamento | | --- | --- | --- | --- | --- | --- | | Conta | Sim | Sim | Sim | Sim | Sim | | Cobrança | Sim | Sim | Sim | Sim | Sim | | Informações da empresa | Não | Não | Não | Sim | Não | | Cliente | Sim | Sim | Sim | Sim | Sim | | Funcionário | Sim | Sim | Sim | Sim | Sim | | Estimativa | Sim | Sim | Sim | Sim | Sim | | Fatura | Sim | Sim | Sim | Sim | Sim | | Item | Sim | Sim | Sim | Sim | Sim | | Pagamento | Sim | Sim | Sim | Sim | Sim | | Preferências | Não | Não | Não | Sim | Não | | Lucros e perdas | Sim | Não | Não | Sim | Não | | Agência tributária | Sim | Sim | Sim | Sim | Sim | | Fornecedores | Sim | Sim | Sim | Sim | Sim | **Exemplo:** ``` QuickBooks_read = glueContext.create_dynamic_frame.from_options( connection_type="quickbooks", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "Account", "API_VERSION": "v3" } ``` **Detalhes de entidade e campo do QuickBooks**: Para obter mais informações sobre os detalhes das entidades e dos campos, consulte: + [Conta](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/account) + [Cobrança](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/bill) + [CompanyInfo](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/companyinfo) + [Cliente](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/customer) + [Funcionário](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/employee) + [Estimativa](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/estimate) + [Fatura](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/invoice) + [Item](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/item) + [Pagamento](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/payment) + [Preferências](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/preferences) + [ProfitAndLoss](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/profitandloss) + [TaxAgency](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/taxagency) + [Fornecedor](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/vendor) ## Particionamento de consultas **Particionamento com base em campo**: No QuickBooks, os campos de tipo de dados Integer e DateTime oferecem suporte a particionamento com base em campos. É 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. + `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. No campo Datetime, aceitamos o formato de carimbo de data/hora do Spark usado em consultas SQL do Spark. Exemplos de valores válidos: ``` "2024-05-07T02:03:00.00Z" ``` + `UPPER_BOUND`: um valor limite superior **exclusivo** do campo de partição escolhido. + `NUM_PARTITIONS`: o número de partições. Exemplo: ``` QuickBooks_read = glueContext.create_dynamic_frame.from_options( connection_type="quickbooks", connection_options={ "connectionName": "connectionName", "REALMID": "12345678690123456789", "ENTITY_NAME": "Account", "API_VERSION": "v3", "PARTITION_FIELD": "MetaData_CreateTime" "LOWER_BOUND": "2023-09-07T02:03:00.000Z" "UPPER_BOUND": "2024-05-07T02:03:00.000Z" "NUM_PARTITIONS": "10" } ``` **Particionamento com base em registros**: A consulta original é dividida em `NUM_PARTITIONS` subconsultas que podem ser executadas pelas tarefas do Spark simultaneamente: + `NUM_PARTITIONS`: o número de partições. Exemplo: ``` QuickBooks_read = glueContext.create_dynamic_frame.from_options( connection_type="quickbooks", connection_options={ "connectionName": "connectionName", "REALMID": "1234567890123456789", "ENTITY_NAME": "Bill", "API_VERSION": "v3", "NUM_PARTITIONS": "10" } ``` # Opções de conexão do QuickBooks Estas são as opções de conexão do QuickBooks: + `ENTITY_NAME`(string): (obrigatório) usado para leitura. O nome do seu objeto no QuickBooks. + `INSTANCE_URL`(string): (obrigatório) um URL de instância válida do QuickBooks. + `API_VERSION`(string): (obrigatório) usado para leitura. Versão da API Rest do QuickBooks que você deseja usar. + `REALM_ID`(string): um ID que identifica uma empresa individual do QuickBooks Online para a qual você envia solicitações. + `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 e notas do conector do QuickBooks Estas são as limitações ou notas do conector do QuickBooks: + Na API `taxAgency`, a ordenação por filtragem não está funcionando conforme o esperado.