在单个操作中从多个Salesforce对象加载和提取数据，保留链接和网络结构。
amaxa的Python项目详细描述
Amaxa—Salesforce的多对象ETL工具
amaxa是salesforce的一个新的数据加载器和etl（extract transform load）工具，旨在支持在单个操作中提取和加载复杂的记录网络。例如，Amaxa操作可以提取指定的一组帐户、它们的关联联系人和机会、它们的机会联系人角色和关联活动，然后将所有这些数据加载到另一个Salesforce组织中，同时保留记录之间的连接。
Amaxa旨在用vlookup（）替换复杂的、易出错的工作流，这些工作流操作数据导出以维护对象关系。
安装、构建和测试Amaxa
使用amaxa需要python 3.6。要使用pip安装amaxa，请执行
$ pip install amaxa
确保在Python3.6+虚拟环境中调用，或者根据操作系统的需要指定Python3.6或更高版本。
Amaxa是操作系统不可知论者。它主要是在Linux上测试过的，但也可以在MingWWindows7环境下工作。
开发
要在虚拟环境中开始使用amaxa，请克隆git存储库。然后，为amaxa创建一个虚拟环境并安装在那里：
$ cd amaxa
$ python3.6 -m venv venv
$ source venv/bin/activate
$ pip install -r requirements.txt -r testing-requirements.txt
$ python setup.py install
然后，只要虚拟环境处于活动状态，就可以从命令行调用amaxa。
Amaxa依赖于以下要运行的包：
简单的SalesforceSalesforce批量pyyamlpyjwt密码学请求cerberus
对于开发和测试，您还需要
pytestpytest covcodecov车轮设置工具
使用pytest执行测试。如果环境变量instance_url和access_token中存在有效的salesforce访问令牌和实例url，则将对该salesforce org运行集成和端到端测试；否则只运行单元测试。请注意，集成测试是破坏性的并且需要在运行之前设置数据。仅在Salesforce DX Scratch组织中运行集成测试（有关特定测试过程，请参见.gitlab ci.yml。
运行amaxa
命令行api非常简单。要提取数据，给定一个操作定义文件op.yml和一个凭证文件cred.yml，运行
$ amaxa --credentials cred.yml op.yml
要执行相同操作定义的加载，只需添加--load：
$ amaxa --credentials cred.yml op.yml --load
操作定义通常构建为支持同一对象网络的加载和提取。有关详细信息，请参见下文。虽然本指南中的示例采用yaml格式，但amaxa在功能奇偶性和相同模式下支持json。
Amaxa提供的另一个命令行开关是--verbosity。支持的级别是quiet、errors、normal和verbose，按详细程度的升序排列。
要查看使用帮助，请执行
$ amaxa --help
提供凭据
凭证以yaml或json文件的形式提供，如下所示（用户名和密码）
version: 1
credentials:
username: 'test@example.com'
password: 'blah'
security-token: '00000'
sandbox: True
Amaxa还允许JWT身份验证，用于无头操作：
version: 1
credentials:
username: 'test@example.com'
consumer-key: 'GOES_HERE'
jwt-key: |
-----BEGIN RSA PRIVATE KEY-----
<snipped>
-----END RSA PRIVATE KEY-----
sandbox: False
如果您的jwt密钥存储在文件的外部，请使用带有该文件名称的密钥jwt file，而不要将密钥包含在内联文件中。
最后，如果在amaxa之外建立身份验证（例如，使用salesforce dx），则可以直接提供访问令牌和实例url。
version: 1
credentials:
access-token: '.....'
instance-url: 'https://test.salesforce.com
定义操作
使用amaxa运行的操作由json或yaml编写的操作定义文件建立。运算操作定义指定要提取或加载的对象的顺序，以及每个对象上需要的字段。Amaxa处理顶级对象及其子对象之间的跟踪关系，并提取一组CSV文件以生成完整的内部一致的数据集。
下面是yaml中amaxa操作定义的示例。
version: 1
operation:
-
sobject: Account
fields:
- Name
- Id
- ParentId
-
field: Description
column: Desc
transforms:
- strip
- lowercase
extract:
query: 'Industry = "Non-Profit"'
-
sobject: Contact
file: 'Contacts-New.csv'
field-group: readable
outside-reference-behavior: drop-field
extract:
descendents: True
-
sobject: Opportunity
field-group: readable
extract:
descendents: True
定义的核心是操作下的sobject列表。我们按提取或加载顺序列出对象。顺序很重要，因为它决定了amaxa如何定位、提取和加载对象之间的关系。通常，应该使用要提取或加载的最高级别对象启动操作定义。这可能是帐户，例如，如果加载带有子对象的自定义对象，则为父对象。然后，我们按顺序列出子对象和其他依赖项。列表中后面列出的对象可以基于与列表中较高的对象的查找或主详细信息关系来提取。（有关对象序列模式的详细信息，请参见下文。）
对于我们选择提取的每个对象，我们回答几个主要问题。
我们要提取哪些记录？
使用提取：键指定记录选择。我们可以指定几种不同类型的记录级提取机制。加载操作期间，将忽略提取键。
$ pip install amaxa
查询的提取类型提取与您提供的soqlwhere子句匹配的记录。（不要在其中包含关键字）。
$ pip install amaxa
子代的提取类型会将具有查找或主详细信息关系的记录提取到操作定义中较高的任何对象。此关系可以是对象的选定字段中包含的任何字段。例如，如果提取帐户后接联系人，并且指定了子代：true，则Amaxa将通过任何查找字段从联系人将与所有提取帐户关联的联系人拉到操作中包含的帐户。例如，这可能包括accountid以及一些自定义字段其他帐户。如果在操作中另一个对象位于contact上方，并且contact与该对象有关系，则Amaxa还将拉取与该对象的提取记录相关联的contact记录。
$ pip install amaxa
ids提取类型通过列表中提供的id提取特定记录。
所有类型的提取也检索依赖关系。当操作中较高的sobject与操作中较低的sobject有关系时，将在稍后的过程中记录和提取引用对象的id。例如，如果account上的included字段是与contact的关系，但account是先提取的，则amaxa将确保在contact步骤中提取所有引用的记录。
依赖和派生关系跟踪的结合有助于确保amaxa根据您提供的操作定义提取并加载组织内部一致的数据片段。
我们要提取或加载哪些字段？
这是用字段或字段组键指定的。
选择字段的最简单方法是指定字段组：[smart readable writeable]。这指示amaxa根据访问级别自动确定要提取的字段：可读的是所有可访问的字段，可写的所有可创建和可更新的字段，智能的将自动为提取操作选择可读的。nd可写用于加载字段组的使用简化了配置文件，但最适合在同一组织或相关组织上执行的提取和加载操作，如从同一生产组织派生的沙盒。这是因为amaxa将提取对记录类型和用户的引用，这些记录类型和用户的id在不相关的组织中可能不同。
如果要在不相关的组织之间移动数据，或者希望为每个sobject指定确切的字段集，请使用fields键。该键的值是一个列表，其元素可以是单个字段的api名称，也可以是一个指定如何加载、提取和转换数据的映射。
$ pip install amaxa
是一个简单的字段规范示例。
$ pip install amaxa
将提取描述字段，命名csv列desc，并对提取的数据应用转换strip（删除前导和尾随空格）和小写（将文本转换为小写）。加载时，amaxa将查找csv列desc，将其映射到描述字段，并对入站数据应用相同的转换。
数据从何而来？
每个sobject的文件键指定一个csv文件。这是加载操作的输入数据，或提取的输出数据。如果未提供密钥，Amaxa将指定sobjectname.csv。
对于加载，amaxa还将使用结果文件键，该键指定输出id映射和错误文件的位置。如果未提供，Amaxa将使用sobjectname results.csv。结果文件有三列："original id"，"new id"，以及"error"
操作中的对象排序
如上例所示，要提取或加载父对象及其子对象，请先列出父对象，然后列出子对象，并为子对象指定提取：子对象的子对象：true。如果父对象本身是更高级别父对象的子对象，您也可以在那里使用子对象-只要确保您的操作定义以至少一个配置有extract:all:true、extract:ids:<；list>；或extract:que的对象开始。ry:<；where子句>；以便amaxa有一个指定的开始记录集。
$ pip install amaxa
在特定情况下，还有其他一些模式是有用的。例如，允许从子对象开始，并允许amaxa将父对象作为依赖项进行拉取。（请注意，在重新加载数据时，这种方法的性能可能会有所降低，因为amaxa必须运行两个过程来填充所有的查找字段）
$ pip install amaxa
在这种模式中，amaxa不会为account找到任何子代（除非account本身对contact进行了查找），但它会将所有提取的联系人的父帐户作为依赖项进行提取，因为accountid字段包含在手术。
可以通过几种不同的方式选择连接对象。假设我们有对象A和B，它们与连接对象C相连。
- 我们要提取特定的A记录，其中包含所有C连接和与其关联的B记录。
我们先指定a，然后指定c，然后指定b。c和b在
提取：下设置了子代：true。 - 我们要提取A和B的所有记录，以及连接它们的C记录
使用
extract:all:true>指定a和b。然后列出c，并使用extract:subdents:true - 我们要提取所有C记录及其关联的A和B记录。
首先使用
extract:all:true指定c。然后按C后面的任意顺序列出A和B，并指定extract:subdents:true。在这种情况下，Amaxa找不到A和B的任何后代记录（因为它们是父记录），但它会自动将与提取的C记录关联的所有记录作为依赖项拉取。 < > > 无，这将完全禁用验证，不建议使用。默认值，它应用上面的默认语义。strict，它将字段组条目视为与字段一样，这意味着文件列和字段之间必须有1:1的匹配。- 两个对象都包含在操作中；
- sobject a高于sobject b；
- sobject b的某条记录上的引用的字段值是未提取的sobject a记录的id。
包含，默认值：在提取的数据中包含外部引用。（如果目标环境中不存在链接记录，则加载时可能抛出错误）。放置字段：提取和加载时将外部引用清空。错误：找到外部引用时停止并记录错误。- amaxa不支持导入或导出复合字段（地址和地理位置），但可以导入和导出其组件字段，例如
mailingstreet - Amaxa不支持base64二进制blob字段。
- 提高API使用效率和内存消耗。
- 更复杂地处理对"元数据"对象的引用，如用户和记录类型。
- 支持从没有Salesforce ID的外部系统导入数据
- 请注意，如果输入数据中的id值符合salesforce id的预期长度和字符内容，则可以手动合成这些值。
- 提取处理外部引用的递归逻辑。
在设计操作时，最好考虑哪些对象是操作的主要对象，并利用子记录跟踪和从属记录跟踪来相应地构建操作序列。
验证
如果指定的操作没有意义或无效，Amaxa会尝试发出警告。
在操作开始之前，将检查sobjects和字段条目。所有条目都将被验证，以确保它们存在并可供正在运行的用户访问。如果无法为加载操作写入或更新字段，Amaxa将显示错误并停止（只有依赖查找必须可更新，但所有字段都必须可创建）。
对于加载操作，amaxa还将验证指定的输入数据是否与操作定义匹配。对于用字段指定的字段列表，在提供的csv中设置的列必须与字段列表完全匹配（考虑到任何指定的列映射）。对于字段组规范，amaxa允许在csv中省略属于字段组的字段，但不允许在csv中添加任何额外字段。如果提供了字段组：smart选项，即使在加载时，Amaxa也始终根据可读的字段组进行验证，但仅尝试加载可写字段。
通过在每个条目中指定键input validation可以在sobject级别控制验证。可接受的值是
处理外部引用和自我查找
Amaxa提供了在两种可能导致问题的情况下控制其引用跟踪行为的选项：自查找和外部引用。
自我查找
自查找是对象与自身之间的关系，例如account.parentid。amaxa的默认行为是通过向上和向下迭代层次结构来处理自我查找，以确保链接到特定提取记录的所有父级和子级也都被提取出来。例如，给定以下帐户层次结构：
$ pip install amaxa
如果我们在提取操作中指定二元操作公司的id，Amaxa将向上递归到合并的行业，然后向下遍历层次结构，最终提取二元操作公司本身、其子公司、其父公司和祖父母，以及其子公司。德伦。然后，如果还指定了像contact这样的子对象，则将提取与整个帐户层次结构关联的记录。
如果不需要此行为，则可以在sobject级别或单个字段项的映射中应用自查找行为键。允许的值是trace all，默认值，或trace none，它禁止以下自查找。
可以在sobject级别和单个字段的映射中配置自查找行为。
外部参考
在Amaxa的术语中，"外部引用"是从Sobject B到Sobject A的引用，其中
如果联系人对帐户有自定义查找，primary\u support\u account\u c，则如果amaxa提取了帐户a、b和ca，则可能会发生外部引用找到他们所有的联系人，然后发现联系人d的primary\u support\u account\u c查找引用了account q-一个不包含在提取中的记录。由于已提取帐户，Amaxa无法将该记录作为依赖项添加。
Amaxa为外部引用提供特殊的处理行为，以帮助确保提取的数据保持引用完整性，并可以安全地加载到另一个组织中。
与自查找一样，外部引用行为由键外部查找行为指定，该键可以放在定义文件的sobject级别或field级别。允许的选项是
请注意，对根本不属于操作一部分的sobject的引用不会被视为外部引用，并且对于此类引用，处理程序行为是非活动的。例如，ownerid字段是对队列或用户对象的引用。如果这些sobject不包含在操作中，则指定外部查找行为：drop field将不会对ownerid字段产生任何影响。当引用非包含的Sobject是操作的一部分时，Amaxa将记录警告。
外部引用行为在具有复杂依赖引用网络的情况下非常有用。如上文所述，与提及自己账户以外账户的联系人很可能构成外部提及。外部引用行为允许从操作中省略此类查找，确保提取的数据不包含悬挂引用。
错误行为和恢复
由于加载复杂对象网络时的错误恢复可能具有挑战性，而且整个加载操作不是原子的，因此强烈建议在Amaxa加载过程中停用所有触发器、工作流规则、进程、验证规则和查找字段筛选器。防止错误比纠正错误容易得多。
amaxa分两个阶段执行加载，称为inserts和dependents。在插入阶段，amaxa按顺序加载每个sobject的记录。在dependents阶段，amaxa运行更新以填充对创建的记录的自查找和依赖查找。在这两个阶段中，当Amaxa从Salesforce收到错误时停止加载数据。由于amaxa使用了大容量api，因此停止发生在sobject的末尾和当前正在处理的阶段。
如果正在加载帐户、联系人和机会，并且在插入联系人期间发生错误，Amaxa将在联系人插入阶段结束时停止。所有成功加载的帐户和联系人都将保留在Salesforce中，但对于依赖项阶段不做任何工作。如果错误发生在依赖项阶段，则所有Sobject的所有记录都已加载，但操作中错误Sobject和所有Sobject的依赖项和自查找都不会填充。
遇到的错误的详细信息显示在出错sobject的结果文件中，默认情况下该文件是sobjectname results.csv，但可以在操作定义中重写。
当amaxa由于错误而停止时，它会保存一个状态文件以保留加载操作的阶段和进度。某些操作的状态文件operationoperation.yaml将被调用operation.state.yaml。状态文件保存已成功加载的旧Salesforce ID到新Salesforce ID的映射，以及发生故障时操作所处的位置。
应该是F发生故障时，您可以采取措施修复故障，包括更改.csv文件中的记录或更改组织中的元数据。然后，您可以通过重复原始命令并添加-s<；state file>；选项来继续加载：
$ pip install amaxa
amaxa将从停止的地方开始，只加载失败或第一次未加载的记录。（您可以在任何sobject中向操作添加记录，如果原始故障在inserts阶段，则amaxa将在恢复时提取这些记录-如果amaxa已达到dependents阶段，则不要添加新记录）。它还将完成所有未执行的过程，以填充依赖和自查找。
API使用
amaxa同时使用rest和bulk api来完成它的工作。
提取时，它为每个sobject使用一个大容量api作业，其中 加载时，对于每个sobject的10000条记录，amaxa使用一个批量api批处理，对于每个sobject的10000条记录，使用一个批量api批处理，每个sobject都有自己或依赖的查找。第二阶段只包括需要依赖处理的记录。 在每个操作上使用少量额外的api调用来获取组织的架构信息。 amaxa包含两个示例数据套件和操作定义文件，它们位于 未来的计划包括： _μαζα是古希腊语中的"马车"一词。 欢迎加入QQ群-->： 979659372
extract设置为all或query，加上由于依赖关系或extract设置为子代而按id提取的每200条记录中大约有一个api调用（对rest api）<·代码>< /P>示例数据和测试套件
assets目录中。请参见每个目录中的about.mdabout.md，以了解有关数据套件包括的内容和测试以及如何使用它的信息。限制、已知问题和未来计划
阿玛莎是什么意思？
推荐PyPI第三方库
