将services配置为webapi
《Magento2.X企业级开发实战》
将服务配置为 Web API
可以将 Magento 或第三方服务配置为 Web API。
要配置 Web API,请在服务模块的 webapi.xml XML 配置文件中定义 XML 元素和属性。
模块的 etc/webapi.xsd 文件指定用于验证的 XML 模式文件。默认的 XML 模式验证规则存储在 vendor/magento/module-webapi/etc/webapi.xsd 文件中。
用户可以进行 REST 或 SOAP 调用来访问 Web API。
要为服务配置 Web API,您需要在 app/code/Custom/<Module>/etc/webapi.xml
文件中定义 XML 元素和属性,其中 <Module>
是模块名称。例如,customer服务 Web API 在 vendor\magento\module-customer\etc\webapi.xml
配置文件中定义。
服务接口要求
使用 webapi.xml 文件配置服务类后,Magento 会使用 Web API 动态地使服务方法可用。因为这是自动生成的,所以以非常特定的方式格式化服务类很重要。
当您考虑到虽然服务类可能需要特定类类型的对象(例如 save 方法)并可能返回一个类或类数组的结果时,这是有道理的,但 SOAP 和 REST 都不能保证定义了该类在客户端甚至有一个类似于 PHP 类的概念。因此,Magento 使用反射来自动创建这些类,并在调用服务方法时将您以 JSON 或 HTTP 数组语法提交的数据设置到预期的 PHP 类的实例上。
相反,如果从这些方法之一返回对象,Magento 会在通过 Web API 发送之前自动将该 PHP 对象转换为 JSON 或 SOAP 对象。
要进行这种转换,Magento 应用程序必须知道有关服务方法期望的参数和服务方法传递的结果的返回类型的信息。 PHP 5.x 不允许对标量参数或返回类型进行类型提示,因此为了将数组或 JSON 对象与适当的类类型相互转换,PHP 依赖于 PHP 文档块。具体来说,包含@param 和@return 的行必须遵循一定的规则,Magento 才能在类型之间正确转换。
Web API 公开的所有方法都必须遵循这些规则
预期作为参数或返回的对象的所有方法都必须遵循这些规则
参数必须在 doc 块中定义为
@param 类型 $paramName
返回类型必须在 doc 块中定义为@return 类型
有效的标量类型包括:mixed(或 anyType)、bool(或 boolean)、str(或 string)、integer(或 int)、float 和 double。
有效的对象类型包括完全限定的类名或完全限定的接口名称。
数组类型的任何参数或返回值都可以在前面的任何类型后面加上一组空的方括号 [] 来表示
以下是各种类型的一些示例以及它们在 doc 块中的外观:
一个参数 $types 可以是一个字符串数组:
@param string[] $types
参数 $id 可以是整数:
@param int $id
参数 $customer 是类\Magento\Customer\Api\Data\CustomerInterface
的对象:
@param \Magento\Customer\Api\Data\CustomerInterface $customer
请注意,即使类\Magento\Customer\Api\Data\CustomerInterface
位于当前类的相同命名空间(或子命名空间)中,或者类顶部存在 use 语句,也必须使用完全限定的命名空间(即以\开头)。
返回类型为 \Magento\Customer\Api\Data\CustomerInterface
的对象数组:
@return \Magento\Customer\Api\Data\CustomerInterface[]
webapi.xml 配置选项
要定义 Web API 组件,请在 webapi.xml 配置文件中的这些 XML 元素上设置这些属性,如下所示:
XML element | Description | Attributes |
---|---|---|
`<routes>` | Required. Root element that defines the namespace and location of the XML schema file. | `xmlns:xsi`. Required. Defines the namespace for the XML schema instance.`xsi:noNamespaceSchemaLocation`. Required. Defines the path and file name of the XML schema file to use to validate the web API. |
`<route>` | Required. Child element of `<routes>`. Defines the HTTP route for the web API method. | `method`. Required. String. HTTP method. Valid values are GET, POST, PUT, and DELETE.`url`. Required. String. The URL to the Magento resource. The string must begin with `/V1` (or `/V<integer>`) to indicate the version number. You must prepend any template parameters with a colon. Example: `/V1/products/:sku`secure`. Optional. Boolean. Indicates that the route is accessible over only HTTPS. Any attempts to access this route over non-secure causes an exception.soapOperation . Optional. String. Specifies the SOAP operation name to use instead of the interface’s method name. Use this element to create multiple operations for the same service contract. |
`<service>` | Required. Child element of `<route>`. Defines the implemented interface and the web API method name. | `class`. Required. String. Location and name of implemented interface.`method`. Required. String. Web API method name. |
`<resources>` | Required. Child element of `<route>`. Container for one or more resource definitions. | None. |
`<resource>` | Required. Child element of `<resources>`. Defines a resource to which the caller must have access. | `ref`. Required. Referenced resource. Valid values are `self`, `anonymous`, or a Magento resource, such as `Magento_Customer::group`. Note:The Magento web API framework enables guest users to access resources that are configured with `anonymous` permission. Any user that the framework cannot authenticate through existing authentication mechanisms is considered a guest user. |
`<data>` | Optional. Child element of `<route>`. Container for one or more parameter definitions. | None. |
`<parameter>` | Required if `<data>` is specified. Child element of `<data>`. Defines a parameter. | `name`. String. Parameter name.`force`. Boolean. Forcing Request Parameters |
示例 Web api.xml 文件
此示例来自定义Customer Service的 Web API 的 webapi.xml 文件:
<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
<!-- Customer Group Service-->
<route url="/V1/customerGroups/:id" method="GET">
<service class="Magento\Customer\Api\GroupRepositoryInterface" method="getById"/>
<resources>
<resource ref="Magento_Customer::group"/>
</resources>
</route>
...
<route url="/V1/customers/me/billingAddress" method="GET">
<service class="Magento\Customer\Api\AccountManagementInterface" method="getDefaultBillingAddress"/>
<resources>
<resource ref="self"/>
</resources>
<data>
<parameter name="customerId" force="true">%customer_id%</parameter>
</data>
</route>
</routes>
说明:
行数 | 说明 |
---|---|
2 | 用于验证 XML 的 XML 架构文件。 XML 模式文件是 `xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:noNamespaceSchemaLocation=”urn:magento:module:Magento_Webapi:etc/webapi.xsd`。 |
4 | 用于访问路由的 HTTP 方法和 Web 资源。 HTTP 方法是 GET。 资源是`/V1/customerGroups/:id`。 用户必须用客户 ID 替换 `id` 模板参数。 |
5 | 路由实现的接口和 Web API 方法的名称。 该路由实现了`Magento\Customer\Api\GroupRepositoryInterface` 接口。 Web API 方法名称是“getById”。 |
7 | 调用者必须有权访问的资源。 调用者必须有权访问`Magento_Customer::group` 资源。 |
17 | 一个必需的参数。 对 `/V1/customers/me/billingAddress` 的 GET 调用需要 `id` 参数。 |
本文来源于:【Magento中文网】,并添加本文地址链接。
如未按上述操作复制或转载,本站有权追究法律责任。
若本站内容侵犯了原著者的合法权益,可联系我们进行处理。