跳到主要内容
将当前页面内容以 Markdown 格式复制到剪贴板

身份验证

WooCommerce 提供了两种与 WP REST API 进行身份验证的方法。 还可以使用任何 WP REST API 身份验证 插件或方法进行身份验证。

REST API key​

预生成的 key 可以用于验证对 REST API 端点的使用。 新的 key 可以通过 WordPress 管理界面生成，或者可以通过一个端点自动生成。

在 WordPress 后台界面生成 API 密钥​

要为特定的 WordPress 用户创建或管理密钥，请转到 WooCommerce > 设置 > 高级 > REST API。

注意：在 WooCommerce 3.4 之前的版本中，“密钥/应用”位于 WooCommerce > 设置 > API > 密钥/应用。

WooCommerce REST API 密钥设置

点击“添加密钥”按钮。 在下一个屏幕上，添加描述并选择您要为其生成密钥的 WordPress 用户。 使用生成的密钥访问 REST API 时，将遵循该用户的 WordPress 角色和权限。

选择此 REST API 密钥的访问级别，可以是 读取 访问、写入 访问或 读取/写入 访问。 然后点击“生成 API 密钥”按钮，WooCommerce 将为选定的用户生成 REST API 密钥。

创建新的 REST API 密钥

现在已生成密钥，您应该会看到两个新密钥、一个二维码和一个“撤销 API 密钥”按钮。 这两个密钥是您的 Consumer Key 和 Consumer Secret。

生成的 REST API 密钥

如果与 API 密钥关联的 WordPress 用户被删除，则该 API 密钥将不再起作用。 API 密钥不会转移到其他用户。

使用我们的应用程序身份验证端点自动生成 API 密钥​

任何应用程序都可以使用此端点，以便允许用户为您的应用程序生成 API 密钥。 这使得与 WooCommerce API 的集成更容易，因为用户只需要通过一个网址授予您的应用程序访问权限。 在被重定向回您的应用程序后，API 密钥将以单独的 POST 请求发送回来。

以下图像说明了其工作原理：

身份验证端点流程

注意

此端点仅用于用户生成 API 密钥并促进 WooCommerce REST API 与应用程序之间的集成。 此端点绝不应被用作客户的登录方法。

URL parameters​

ParameterTypeDescription
app_namestringYour APP name MANDATORY
scopestringLevel of access. Available: read, write and read_write MANDATORY
user_idstringUser ID in your APP. For your internal reference, used when the user is redirected back to your APP. NOT THE USER ID IN WOOCOMMERCE MANDATORY
return_urlstringURL the user will be redirected to after authentication MANDATORY
callback_urlstringURL that will receive the generated API key. Note: this URL should be over HTTPS MANDATORY

创建一个身份验证端点网址​

您必须使用 /wc-auth/v1/authorize 端点，并将上述参数作为查询字符串传递。

以下是一个构建身份验证网址的例子：

# Bash example
STORE_URL='http://example.com'
ENDPOINT='/wc-auth/v1/authorize'
PARAMS="app_name=My App Name&scope=read_write&user_id=123&return_url=http://app.com/return-page&callback_url=https://app.com/callback-endpoint"
QUERY_STRING="$(perl -MURI::Escape -e 'print uri_escape($ARGV[0]);' "$PARAMS")"
QUERY_STRING=$(echo $QUERY_STRING | sed -e "s/%20/\+/g" -e "s/%3D/\=/g" -e "s/%26/\&/g")

echo "$STORE_URL$ENDPOINT?$QUERY_STRING"

使用 API 密钥发布的 JSON 例子。

{
    "key_id": 1,
    "user_id": 123,
    "consumer_key": "ck_xxxxxxxxxxxxxxxx",
    "consumer_secret": "cs_xxxxxxxxxxxxxxxx",
    "key_permissions": "read_write"
}

用户将看到的屏幕示例：

身份验证端点示例

注意事项​

  • 在使用 return_url 重定向用户时，您还会收到 success 和 user_id 参数作为查询字符串。
  • 如果用户拒绝，success 会发送 0；如果身份验证成功，则发送 1。
  • 使用 user_id 来标识在重定向回 (return_url) 时识别用户，并且请务必在您的 callback_url 在身份验证后被 POST 到时保存 API 密钥。
  • 身份验证端点会将 API 密钥以 JSON 格式发送到 callback_url，因此请记住，某些语言（例如 PHP）不会将其显示在 $_POST 全局变量中；在 PHP 中，您可以使用 $HTTP_RAW_POST_DATA（适用于旧版本的 PHP）或 file_get_contents('php://input'); 来访问它。
  • 生成的 URL 必须对所有查询字符串值进行编码。

通过 HTTPS 进行身份验证​

您可以 使用 HTTP Basic Auth，方法是提供 REST API Consumer Key 作为用户名，以及 REST API Consumer Secret 作为密码。

curl https://www.example.com/wp-json/wc/v3/orders \
    -u consumer_key:consumer_secret

有时，某些服务器可能无法正确解析 Authorization 页眉（如果在使用 SSL 进行身份验证时看到“缺少 Consumer key”错误，则表明存在服务器问题）。 在这种情况下，您可以将 consumer key/secret 作为查询字符串参数提供。

对于那些未能正确解析 Authorization 页眉的服务器的例子：

curl https://www.example.com/wp-json/wc/v3/orders?consumer_key=123&consumer_secret=abc

通过 HTTP 进行身份验证​

您必须使用 OAuth 1.0a "单腿" 身份验证 来确保 REST API 的凭据不会被攻击者拦截。 通常，您将使用所选语言中的任何标准的 OAuth 1.0a 库来处理身份验证，或者按照以下说明生成必要的参数。

创建签名​

收集请求方法和 URL​

首先，您需要确定将用于请求的 HTTP 方法以及请求的 URL。

HTTP 方法 在我们的例子中是 GET。

请求 URL 将是您要发送到端的 URL，例如 http://www.example.com/wp-json/wc/v3/orders。

收集参数​

收集并规范化您的参数。 这包括所有 oauth_* 参数，除了 oauth_signature 本身。

这些值需要编码成一个字符串，稍后将用于其他用途。 构建该字符串的过程非常具体：

  1. 对每个将被签名的键和值进行 百分比编码。
  2. 按编码后的键的字母顺序对参数列表进行排序。
  3. 对于每对键/值：
    • 将编码后的键附加到输出字符串。
    • 将 = 字符附加到输出字符串。
    • 将编码后的值附加到输出字符串。
    • 如果还有剩余的键/值对，则将 & 字符附加到输出字符串。

例如，在 PHP 中进行百分比编码时，您可以使用 rawurlencode() 函数。

例如，在 PHP 中对参数进行排序时，您可以使用 uksort( $params, 'strcmp' ) 函数。

参数示例：

oauth_consumer_key=abc123&oauth_signature_method=HMAC-SHA1

创建签名基础字符串​

前面收集到的所有值必须连接成一个单独的字符串，该字符串用于生成签名。在 OAuth 规范中，这被称为签名基础字符串。

要将 HTTP 方法、请求网址和参数字符串编码为一个单独的字符串：

  1. 将输出字符串设置为 HTTP 方法 的大写形式。
  2. 将 & 字符附加到输出字符串。
  3. 对网址进行 百分比编码，然后将其附加到输出字符串。
  4. 将 & 字符附加到输出字符串。
  5. 对参数字符串进行 百分比编码，然后将其附加到输出字符串。

示例签名基础字符串：

GET&http%3A%2F%2Fwww.example.com%2Fwp-json%2Fwc%2Fv3%2Forders&oauth_consumer_key%3Dabc123%26oauth_signature_method%3DHMAC-SHA1

生成签名​

使用 签名基础字符串 和您的消费者密钥，通过 & 字符，并使用 HMAC-SHA1 哈希算法生成签名。

在 PHP 中，您可以使用 hash_hmac 函数。

HMAC-SHA1 或 HMAC-SHA256 是唯一支持的哈希算法。

如果您在生成正确签名时遇到问题，请检查您正在签名的字符串是否存在编码错误。 身份验证源 也可以帮助您了解如何正确生成签名。

OAuth 提示​

  • OAuth 参数可以作为查询字符串参数添加，或者包含在 Authorization 页眉中。
  • 请注意，在 WordPress 中没有可靠的跨平台方法来获取原始请求头信息，因此在某些情况下，查询字符串可能更可靠。
  • 必需的参数是：oauth_consumer_key, oauth_timestamp, oauth_nonce, oauth_signature 和 oauth_signature_method。 oauth_version 不是必需的，应省略。
  • OAuth 随机数可以是任何唯一的、随机生成的 32 个字符（推荐）字符串，该字符串与消费者密钥相关联。
  • OAuth 时间戳应该是请求时的时间戳。 REST API 会拒绝包含超出 15 分钟窗口的时间戳的任何请求，以防止重放攻击。
  • 您必须使用索引提供的商店 URL 来构建用于签名的基础字符串，因为服务器将使用它。（例如，如果商店 URL 包含 www 子域名，您应该在请求中使用它）
  • 请注意，根据 OAuth 规范，请求体 不 进行签名。
  • 如果要在请求中包含参数，则按字母顺序排列这些参数可以避免很多问题。
  • Authorization 页眉从 WooCommerce 3.0 开始支持。