upcc/gsx-rest-php

苹果GSX RESTful API的接口

维护者

详细信息

github.com/UniversityPCCare/gsx-rest-php

主页

源代码

问题

安装: 4

依赖项: 0

建议者: 0

安全性: 0

星级: 13

关注者: 4

分支: 6

开放性问题: 2

dev-master 2023-11-08 17:54 UTC

Requires

  • php: ^7.0
  • ext-curl: *
  • ext-json: *
  • ext-mysqli: *
  • ext-pdo_mysql: *

GPL-3.0-or-later 74b05a976923ca165973156fbf36d9fe565e1d3c

This package is not auto-updated.

Last update: 2024-09-25 21:42:56 UTC

README

GSX-Rest是一个用于与苹果GSX REST API交互的PHP库。它是用于与苹果GSX SOAP API交互的filipp/gsxlib的精神继承者，后者于2019年末被淘汰。

要求

  • PHP >7.0
  • MySQL（用于授权令牌持久化）
  • GSX客户端证书和配置（见下文）
  • GSX账户，在MyAccess中启用了“Web Services”权限（见下文）

安装

  • 使用 git clone https://github.com/UniversityPCCare/gsx-rest-php.git 克隆仓库
  • 如果您还没有，设置一个MySQL实例。创建一个数据库（默认数据库名为 gsxrest）并关联一个用户。或者，在 config/config.ini 中，您可以提供一个具有足够权限创建数据库的用户，数据库将由您创建。
  • 将 config/config.ini.example 重命名为 config/config.ini 并设置默认配置值
  • (可选) 将 tests/test_declarations.php.example 重命名为 tests/test_declaration.php 并在其中设置变量。这仅当您选择运行 tests/test.php 来验证您的设置是否正常时才需要。
  • (可选) 在设置 test_declarations.php 后，cd tests 并运行 php ./test.php
  • 首次运行时，将为您创建数据库（如果尚未创建），以及数据库中的表。

从v1升级到v2 REST API

苹果对其API的v2版本进行了修改。所有认证函数都必须通过 /api 进行，而所有GSX API请求都必须通过 /gsx/api 进行。此外，还有一个新的基本URL。

如果您是从v1升级的，请在 config.ini 中进行以下更改

  • 将变量 REST_BASE_URL 更改为在eServiceCentral中找到的适当基本URL。基本URL在v2中已更改。
  • 添加变量 REST_AUTH_PATH 并将其值设置为 /api
  • 添加变量 REST_GSX_PATH 并将其值设置为 /gsx/api
  • 添加变量 API_VERSION 并将其值设置为 v2。必须精确地按此处所示键入。

配置

此库可以通过在 config.ini 文件中设置值或通过传递一个关联数组的方式来配置，该数组包含以 key => value 格式传递的选项。例如，["SOLD_TO" => "0123456789", ... ]

基本配置需要以下参数

  • PHP_TZ：一个有效的 PHP 时区（例如 America/New_York）
  • STORAGE：持久化的存储方法。目前仅支持MySQL，但计划支持SQLite。
  • [DATABASE]：一组MySQL连接参数（HOST、PORT、DB、USER、PASS）

REST和SOAP API都需要以下参数

  • SOLD_TO：由苹果提供的您的售出账号号码

REST API需要以下参数

  • REST_CERT_PATH：到 .pem 格式证书包的路径。这将是从苹果那里获得的带有您的私钥附加的 AppleCare-Partner-##########.Prod.apple.com.chain.pem 文件。请注意，您必须为每个API请求单独请求证书。请将其保存在安全的地方，不要放在您的Web目录中！
  • REST_CERT_PASS：您的私钥密码。
  • REST_BASE_URL：用于调用REST API的基础URL，可在eServiceCentral找到。
  • ACCEPT_LANGUAGE：接受语言头。默认为en_US。其他选项可在eServiceCentral找到。

SOAP API已弃用，并将从本库中删除。在Apple完全替换SOAP API之前，此库将实现所有遗留SOAP函数。SOAP API需要以下参数

  • SOAP_CERT_PATH：.pem格式证书包的路径。类似于REST_CERT_PATH，这是由Apple提供的“chain.pem”证书，并附加了您的私钥。请注意，您必须请求单独的证书，每个API一个。
  • SOAP_CERT_PASS：私钥密码，如果您为SOAP证书使用了单独的私钥。
  • SOAP_WSDL_URL：WSDL文件的路径。这可以是Apple提供给您的URL（在这种情况下，您的程序将必须为每个GSXHandler实例单独发送HTTP请求以检索WSDL），或者您可以将文件下载并存储在某个位置（例如在config/文件夹中），并将此变量设置为下载文件的路径。
  • SOAP_ENVIRONMENT：将是ut（测试环境）或it（生产环境）。
  • SOAP_REGION：您的区域代码，请参阅GSX中REST API文档中的有效代码（默认为am，代表美洲）。
  • SOAP_TIMEZONE：时区缩写（默认：EST）。
  • SOAP_LANGUAGE：有效的语言代码（默认：en，代表英语），根据GSX REST API文档。

使用方法

设置config\config.ini之后

<?php

require_once("../src/GSXHandler.php");

$gsx = new UPCC\GSXHandler($gsxUserEmail, $gsxShipTo);
$productDetails = $gsx->ProductDetails($serial);
echo $productDetails->device->configDescription;
> iPhone XS Max

实现端点

所有REST API端点至少以基本形式实现，这意味着每个端点至少有一个对应函数，该函数以数组作为输入并返回REST API的响应，或者在无/无效响应时返回NULL。此基本函数不执行错误检查或数据验证，因此假设传递给它的数组格式为REST API可以接受的格式，并且值是有效的。数组应格式化为，当通过json_encode传递时，将生成符合eServiceCentral中该端点文档的JSON请求体。
接受GET请求而不是POST的端点将不接受JSON体，而是接受端点预期的任何查询参数。一些POST端点除了JSON请求体还接受查询参数。

具有辅助函数的端点

以下端点有额外的函数来帮助构建请求体。一些更复杂的端点（如寄售验证请求）有相关的辅助类，可以帮助您构建有效的请求体。

维修

  • /repair/summary
    • RepairSummaryByIds($ids)
    • RepairSummaryById($id)
  • /repair/eligibility
  • /repair/update
  • /repair/product/serializer
    • RepairEligibilityByDeviceId($id)
  • /repair/questions
    • QuestionsLookupByComponentIssue($id, $componentCode, $issueCode, $reportedBy)
  • /repair/loaner/return
  • /repair/create
  • /repair/product/componentissue
    • ComponentIssueLookupByCode($code)
    • ComponentIssueLookupByCodeAndId($code, $id)
    • ComponentIssueLookupById($id)
  • /repair/product/details
    • ProductDetails($id)
  • /repair/product/serializer/lookup
    • ProductSerializerLookupByCode($languageCode)
    • ProductSerializerLookupById($id, $languageCode)

诊断

  • /diagnostics/lookup
    • DiagnosticsLookupByDeviceId($id, $maximumResults=null)

寄售

  • /consignment/validate
  • /consignment/delivery/acknowledge
  • /consignment/order/shipment
  • /consignment/order/lookup
  • /consignment/delivery/lookup
    • ConsignmentDeliveryLookupByStatus($code)
  • /consignment/order/submit

内容

  • /content/article/lookup
    • ArticleIdLookupByDeviceId($id, $pageSize=null, $pageNumber=null)

其他

  • /document-download (POST)
    • DownloadConsignmentProforma($shipmentNumber, $shipTo)
    • DownloadConsignmentPackingList($shipmentNumber, $shipTo)
    • DownloadDepotShipper($id)
  • /attachment/upload-access
    • 附件上传访问多重（$id, $attachments）
    • 附件上传访问单一（$id, $sizeInBytes, $fileName）
  • /parts/summary
    • 按设备ID汇总部件（$id）
    • 按组件问题汇总部件（$id, $componentCode, $issueCode）
  • /technician/lookup
    • 按姓名查找技术人员（$firstName, $lastName, $shipTo=null）

GSX 客户端证书和配置

您需要与 GSX 网络支持团队合作以获取以下内容

  • 由苹果公司签发的证书包，用于 REST API（通常需要几天工作时间）
  • 由苹果公司签发的证书包，用于 SOAP API
  • 您的静态IP地址已列入白名单（可能需要一周时间）

按照苹果公司的 eServiceCentral 中的初始设置指南开始。

具有“Web 服务”权限的 GSX 账户

您（或任何具有 MyAccess 管理访问权限的人）需要在 MyAccess 中至少设置一个账户，以便为 GSX 获取“Web 服务”权限。