了解有关使用 Aconex 数据集成企业软件应用程序或开发第三方应用程序的信息。
借助 Aconex API，您可以：
本开发者指南旨在为希望集成企业软件应用程序或使用Aconex中的数据开发第三方应用的开发人员提供有关Aconex web 服务的全面信息。
技术
Aconex Web 服务设计为独立于编程语言和平台，并使用 RESTful方式的实施，如HTTPS，URL 和 XML 等通用标准。至少，希望使用 Aconex Web 服务的开发人员应该熟悉以下技术/概念：
REST 接口
Aconex 网络服务基于 REST (代表性状态转移)的概念。要访问这些服务，必须构建符合 HTTPS 标准的请求并使用 REST 原则。
XML
Aconex Web 服务当前以 XML 格式返回所有响应，OAuth Services 除外，OAuth Services 以 JSON 格式返回响应。
安全
Aconex Web 服务设计为完全无状态，这意味着主叫方必须在每次请求中提供有效的用户凭据。验证用户的帐户必须处于活动状态，且用户必须有权访问相关项目。所有请求也必须通过端口443上的 HTTPS。任何未通过加密信道执行的请求都将被拒绝。
目前支持两种类型的身份验证：
注意：对于启用了 SSO (单点登录)或2SV (双重验证)的用户帐户，只能使用 OAuth2。
基本身份验证
用户名和密码将在请求中使用 基本身份验证原则 提供。
Authorization: Basic base_64_encoded_username_and_password
请求标题示例：
Authorization: Basic cG9sZWFyeTpBdXRoM250MWM=
下面是一个使用 curl (基于命令行的 Unix 工具，用于执行 Web 请求)在项目收件箱上执行邮件搜索的示例：
curl -u user:password https://{hostname}/api/projects/{projectid}/mail?mail_box=inbox
在这里，用户名和密码是指用于登录 Aconex 的用户名和密码。使用curl，wget (或任何编程库)等标准客户端通常会使用base64编码自动加密用户名/密码。
在请求标题中使用的访问令牌：
Authorization: Bearer ACCESS_TOKEN
可以使用本规范中描述的 Aconex API OAuth2服务获取访问令牌。这涉及用户授权应用程序访问的步骤。和访问令牌一起的是一个刷新令牌。使用刷新令牌，可以无限更新访问令牌，除非用户的授权访问被撤销。了解更多有关 OAuth的信息。
请求标题示例：
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJlbWFpbCI6ImFodXNzZWluIiwiZXhwIjoxNDQwMTUyMzYxLCJzY29wZSI6W10sImNsaWVudF9pZCI6ImGwaXRlc3QifQ.Y0PH3VLnRpXp_95mEL40bbBfJLq1cnU3aHMwyGYiJVttpBFfh-0v7uJWlaSDK2SnU5YLH7DJHk-_454TMIJkZHQRxln4hwJTaXPqrpp1_vffJjXkIBd0piA6NahhDTdWsKHnG3uQxrNdy85fTp9KQgmD3KPXDUsfUomyQD8HsgTrwhm0r2WFIWz7xO_OMQlKI-ahYAi7GRReHS83B3SY_zxM_ZR15F16MCkvZ3e5ZkmsAbFsj9uVxzem2_2HwnJmV3dOLh7IAP1g16Q2syPeZI3Uqj17W3fkJieQOmyqiCJ8M9h-2gUYdF4evVg30vFo4ZkAPXo1QkrFyf2a8db6sg
如何对 OAuth 客户端发请求？
如何请求 API 密钥？
要使用 Aconex API 服务访问 Aconex 项目数据，请联系您的 Oracle Aconex 代表请求访问。每个使用中的API 应用都需要自己的应用密钥。
使用 API 应用密钥，该密钥将添加到请求标题中：
X-Application-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
对于 Field API，请使用 X-Application：
X-Application: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Aconex API 服务支持版本控制。请求响应或请求内容可能因使用的版本而异。使用的版本在请求标题中指定。默认版本为版本1。版本控制用于避免在 API 服务中引入突破性的更改，从而允许开发人员有时间按自己的速度迁移到新版本。最终，旧版本将被折旧并最终删除。
不同的 API 服务组(邮件，文档，项目等)都有自己的版本。所有当前的 API 服务都设置为默认版本1。
GET和PUT方法服务的请求版本在“Accept”标题中指定，请参见下表中的值。用于 POST 方法服务的版本在“Content-Type”标题中指定。整个有效负载的“Content-Type”值必须为“multipart/mixed”。XML 部件的“Content-Type”包含下表中的版本值，标题必须直接出现在所用边界标识符后面的下一行，并且标题后面必须有一个空行，然后才会显示 XML 有效负载。
版本2“GET或PUT邮件服务”接受标题示例：
Accept: application/vnd.aconex.mail.v2+xml
版本2的POST邮件服务content-type示例：
... ------------------------------8d314ec2031d2eb Content-Type: application/vnd.aconex.mail.v2+xml ...
|
组 |
版本 |
值 |
意见 |
|
邮件 |
1 |
无或"application/xml" |
默认 |
|
邮件 |
2 |
"application/vnd.aconex.mail.v2+xml" |
－ |
|
邮件 |
3 |
"application/vnd.aconex.mail.v3+xml" |
－ |
|
文档 |
1 |
无或"application/xml" |
默认 |
|
目录 |
1 |
无或"application/xml" |
默认 |
|
项目 |
1 |
无或"application/xml" |
默认 |
|
任务 |
1 |
无或"application/xml" |
默认 |
每次调用 Aconex Web 服务时，都必须包括本文档“安全”一节中详细介绍的身份验证信息。每个服务的调用将不尽相同，需要提供特定于服务的参数。所有 Aconex Web 服务的通用基本路径如下：
https://{hostname}/api/
为了简单起见，下面显示了一些 Web 服务调用示例：
1.在组织用户“jdoe”的邮件收件箱中搜索项目编号“100”
curl -u jdoe:s3cr3t https://{hostname}/api/projects/100/mail?mail_box=inbox
2.在组织用户“jdoe”的注册表中搜索项编号“100”
curl -u jdoe:s3cr3t https://{hostname}/api/projects/100/register
3.获取用户'jdoe'所属的项目标识'100'的文档架构
curl -u jdoe:s3cr3t https://{hostname}/api/projects/100/register/schema
一些 Aconex Web 服务希望以 XML 形式发布内容以及文件数据(例如注册文档和创建邮件)。这些请求的内容类型必须设置为multipart/mixed，并且必须符合 Internet 标准 RFC 1521 - MIME (多部分 Internet 邮件扩展)中定义的结构。接受多部件请求的每个服务都有自己的先决条件和条件。包含二进制文件数据的所有多部分必须采用 base64编码。
在本文中，hostname 是指相关项目数据所在的 Aconex 实例的唯一地址。Aconex 在世界各地托管了多个实例，因此，您必须构建服务调用以解决项目的相应实例。
Aconex Web 服务可能会返回必须正确处理的错误代码。由于请求结构不正确，登录失败或内部系统错误，可能会返回错误。所有错误响应的结构与以下示例中所示的结构相同(邮件创建 API 版本3提供的合并验证错误响应除外)。
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<ErrorCode>CANNOT_SUPERSEDE_LOCKED_DOCUMENT</ErrorCode>
<ErrorDescription>Cannot supersede document 6590 which is locked</ErrorDescription>
<RequestID>g5g8l8dk</RequestID>
<SystemTime>2010-02-09T16:13:44.208+11:00</SystemTime>
</Error>
每个错误响应将包含：
某些错误代码可以由多个服务返回，而其他错误代码则是特定服务独有的。确保在分析错误时考虑错误代码的上下文。还应注意的是，虽然错误响应中向最终用户提供了错误描述，但它并不一定要显示给使用第三方应用程序的客户端。某些错误描述可能是技术性的。使用错误代码以及操作的上下文，为使用应用程序的最终用户设计一条用户友好的错误消息。
虽然许多错误是单个 API 服务特有的，但下面列出了常见的错误，这些错误可能会在所有 API 服务中针对所有请求发生，因此应该正确处理。
|
错误代码 |
错误描述 |
HTTP 状态代码 |
|
LOGIN_FAILED |
提供的登录凭据验证过程失败 |
400 |
|
ACCESS_FAILED_FOR_ORG |
执行请求的用户的组织尚未获得 Web 服务 API 的访问权限 |
400 |
|
ACCESS_FAILED_FOR_PROJECT |
未向执行请求的用户提供对指定项目上 Web 服务 API 的访问权限 |
400 |
|
API_NOT_ENABLED_FOR_PROJECT |
请求中缺少 API 密钥或未为指定的项目启用 Web 服务 API |
400 |
|
PROJECT_DISCONNECTED |
请求中指定的项目已断开连接 |
400 |
|
PROJECT_NOT_ACTIVE |
请求中指定的项目已被取消激活 |
400 |
|
ACCESS_FAILED_FOR_USER |
未向执行请求的用户提供对 Web 服务 API 的访问权限 |
400 |
|
USER_NOT_ON_PROJECT |
执行请求的用户不在指定的项目上 |
400 |
|
USER_ACCOUNT_LOCKED |
执行请求的用户的帐户已被锁定 |
400 |
|
USER_ACCOUNT_DISABLED |
执行请求的用户已禁用其帐户 |
400 |
|
USER_PASSWORD_EXPIRED |
用户的密码已过期，需要重置 |
400 |
|
user_password_reset |
用户密码已由管理员手动重置 |
400 |
|
NO_SUITABLE_AUTHENTICATION_METH OD |
请求中未找到合适的身份验证方法，即不存在基本身份验证标头 |
400 |
|
TWO_STEP_VERIFICATION_REQUIRED_ FOR_ACCESS |
用户需要两步验证才能访问 Aconex |
403 |
|
SSO_REQUIRED_FOR_ACCESS |
用户需要 SSO 才能登录 |
403 |
|
错误代码 |
错误描述 |
HTTP 状态代码 |
|
INTERNAL_ERROR |
发生了未预期的内部系统错误 |
500 |
|
INVALID_PARAMETER_VALUE |
为其中一个查询或路径参数提供的值无效 |
400 |
|
OPERATION_DEPRECATED |
此操作的版本不再可用 |
405 |
|
OPERATION_NOT_SUPPORTED |
无法找到请求所针对的操作 |
405 |
|
PROJECT_NOT_FOUND |
未找到请求路径中指定的项目 |
400 |
|
UNEXPECTED_PARAMETER |
请求中提供的参数不是目标服务所期望的 |
400 |
系统可能会为有效请求返回 INTERNAL_ERROR。如果发生这种情况，请通过 API 支持论坛联系 Aconex，并提供以下详细信息，以便完成对原因的调查：
API 调用者可以使用 Aconex Web 服务发出的请求的数量和频率都有合理的限制。这些限制已经到位，以确保所有用户，特别是 Aconex Web 界面的用户都能享受到优质的服务。Web 服务 API 应用的限制基于以下条件：
|
状态代码 |
说明 |
HTTP 状态代码 |
|
CONCURRENCY_THROTTLE_LIMIT_REACHED |
已达到用户可以执行的最大并发请求数。 |
503 |
|
MAX_FREQUENCY_THROTTLE_LIMIT_REACHED |
向 Web 服务 API 发出请求的频率已超过服务器施加的限制。您应该减少请求的频率。 |
503 |
字符编码
Aconex Web 服务中使用的字符编码为 UTF-8，用于请求和响应消息。无效输入将被拒绝。
多语言内容
内容将以最终用户提供的格式返回，不带任何语言标识，因此您的应用程序应“按原样”使用此内容。
本地化
根据 Aconex 支持的区域设置，Web 服务可能会返回一些数据。Aconex Web 服务当前将在用户首选项指定的区域内返回数据。目前无法请求区域设置与请求一起使用。
如果您有与 Aconex Web 服务相关的技术支持查询，请与 Oracle 支持部门联系。
