标准

查看API文档

API标准

AEMO用于api的标准是OpenAPI规范(OAS)。有关更多细节，请参阅OpenAPI-Specification:https://github.com/OAI/OpenAPI-Specification．

设计原则

REST方法使用HTTP的特性来使用以下设计原则发出请求:

  1. HTTPS协议通过MarketNet或

  1. 资源被映射到uri层次结构中的位置，例如:service host/system/business_function。

    1. 层次结构的根表示web服务或API应用程序，并提供资源

    2. 下一层提供关于资源的特定信息，

    3. 最后一层提供来自特定资源的数据。有关详细信息，请参阅下面的URL格式。

  2. 容纳各种有效负载，如XML或JSON。

URL格式

API的url格式如下:

参数

描述

协议

HTTPS

Web服务主机

托管服务或外部代理的服务器的名称。

Business_function

API名称-提供服务的AEMO系统，例如GeneratorRecall

资源

业务功能的实体，例如/listRecallPlans

查询字符串参数?

用于GET方法

例子:

格式示例

https://web服务主机/business_function/APIversion/resource?查询字符串参数

互联网URL示例

https://apis.prod.www.thegroupof7.com:9319/ws/GeneratorRecall/1.0/listRecallPlans

MarketNet URL示例

https://apis.prod.marketnet.net.au:9319/ws/GeneratorRecall/1.0/listRecallPlans

头

头参数

描述

允许的值/例子

内容类型

HTTPS请求格式。

内容类型:application / json

接受

HTTPS响应格式。

接受:application / json

内容长度

文件的内容长度。该值在发送请求时填充。

某某内容长度:

X-initiatingParticipantID

与会者ID

X-initiatingParticipantID: 123456

x市场

请求应用的市场类型。

x市场:气体

授权

指定基本HTTP身份验证，包含Base64[1]编码的用户名和密码。参与者的URM用户名和密码用冒号分隔符连接，然后对Base64进行编码。

授权:基本QFhQVC0wMDAwMzoyZWRmOGJhYS0wY2I0LTQwZjctOTIyMS0yODUxNmM4N2MxNjQ=(对于URM用户名“@XPT-00003”和密码“2edf8baa-0cb4-40f7-9221-28516c87c164”)

方法

HTTPS方法

操作

细节

得到

检索数据

GET方法在URL中有查询字符串参数。

GET方法没有在HTTP请求中传递的Content-Type。

并非所有AEMO的api都使用GET方法。

帖子

Post数据

POST方法有:

  • URL中没有查询字符串参数。

  • BASIC认证细节，用户名和密码编码并传递到请求头中。

  • 特定于API的HTTP请求头参数(如果有的话)。

  • 负载的例子:

｛

“ParticipantId”:“PID”,

“StartDate可以”:“2017 - 11 - 01 t00:00:00 + 10”、“EndDate”:“2017 - 11 - 02 - t00:00:00 + 10”,

:“StationId PID6”,

:“DUID AEMO1”,

:“OutagePlanId MMS_GEN_OUT1”

｝

删除

删除数据

DELETE方法在URL中有查询字符串参数。

HTTP响应码

HTTP响应有:

  • 一个响应代码和描述，带有

    • 请求成功，由200表示

    • 其他用于技术和有效载荷验证的响应代码

  • 可选的有效载荷

状态码

当任何技术验证失败时，e-Hub将发送适当的HTTP响应代码和响应有效负载。

代码

条件

描述

200

表示请求成功。

好吧

400

无效的API URI

无法为端点引用(EPR)找到服务，URI， "Fault": "SystemMessageExceptionDump"

401

无效的证书

HTTP请求头中没有BASICAuth信息

未经授权的

"异常":"未经授权:无效的用户名或密码"

404

资源未找到

"异常":"没有找到端点URI的资源。端点

URI:资源”

405

使用的方法无效(例如使用GET而不是POST)

输入请求HTTP方法是无效方法通过，但操作(资源名)只接受:(vValid方法)"

422

业务验证失败

Unprocessable实体

429

超过节流限制

“异常”:“入站请求数量超过了限制;过一段时间再试试。”

500

e-Hub可运行，但下游系统不可用或负载格式不正确(JSON)

"Exception": "应用程序不可用"

交通管理

为了防止后端服务过载，AEMO的API平台实施了流量限制。各API的流量限制请参见各API策略。

连接和读取超时设置

我们建议参与者在调用AEMO的api时使用以下设置。

类型

问题

推荐设置

连接超时

无法连接到e-Hub的端点(例如，e-Hub基础设施不可用)。

10秒

读取超时

已连接到端点，但e-Hub在配置的时间内没有响应。

30秒

术语表

缩写/学期

解释

API网关

AEMO一侧的网关提供参与者通信选项，可通过互联网或市场网络访问。它使用资源和方法将消息推送到参与者的API网关

API

应用程序接口;各种软件组件之间的一组明确定义的通信方法。

API门户

在这里您可以查看可用的API，查看API文档(包括OpenAPI Specs)并获得Postman集合。

企业社会责任

证书签名请求是在申请TLS证书时提供给证书颁发机构的编码文本块。它还包含要包含在证书中的公钥。通常，同时创建一个私钥，构成一个密钥对。

eHub

由电力和天然气的API门户和API网关组成。

JSON

JavaScript对象表示法

密钥对

TLS使用一种称为公钥加密的技术，该技术基于密钥对的概念。密钥对由加密的公钥和私钥数据组成。只能用相应的私钥来解密公钥。

MarketNet

AEMO的专用数据网络连接。

MSATS

零售市场结算及转账系统

美洲国家组织

OpenAPI规范

参与者API网关

由参与者实现的接口，AEMO的API在其中推送消息。

参与者ID

注册参与者标识符

有效载荷

由POST请求发送的数据。Payload部分位于header之后。

PID

参与者ID

私钥

秘密私钥是一个文本文件，最初用于生成证书签名请求(Certificate Signing Request, CSR)，后来用于保护和验证连接。

公钥

公钥作为TLS证书的一部分，与您的私钥一起工作，以确保您的数据被加密、验证和不被篡改。任何有权访问公钥(即证书)的人都可以验证数字签名的真实性，而无需知道秘密的私钥。

肥皂

简单对象访问协议

的文件

API的OpenAPI规范(OAS)定义。

TLS

传输层安全，提供API通信安全的加密协议。

WSDL

Web服务描述语言

XML

可扩展标记语言