---
title: "productByHandle"
description: "通过 handle 查找产品"
doc_type: graphql
doc_category: adminGraphQL
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/products-and-collections/queries/product-by-handle'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/products-and-collections/queries/product-by-handle.md'
---
# productByHandle

通过 handle 查找产品

- **API Version:** v20270301
- **API Type:** Admin
- **API Protocol:** GraphQL
- **Operation Type:** Query

## Type Signature

`Product`

## Arguments

* `handle`

  [String!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/string.md)

  用于识别产品的唯一字符串。该 `handle` 是根据产品标题生成的，转换为小写，并格式化为用连字符替换空格和特殊字符。如果多个产品具有相同的标题，`handle` 会自动附加一个数字来区分它们。例如，如果有两个标题为“Clothing”的产品，则它们的句柄将为“clothing”和“clothing-1”。修改产品标题不会更新句柄

## Returns

* `collections`

  [CollectionConnection](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/products-and-collections/objects/collection-connection.md)

  包含该产品的分类的列表

* `compareAtPriceRange`

  [ProductCompareAtPriceRange](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/products-and-collections/objects/product-compare-at-price-range.md)

  以默认商店货币表示的产品原价范围

* `createdAt`

  [Date!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/date.md)

  创建产品时的日期和时间

* `descriptionHtml`

  [String](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/string.md)

  产品的描述，包括 HTML 格式

* `featuredImage`

  [Image](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common-objects/objects/image.md)

  产品特色图片

* `featuredMedia`

  [Media](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common-objects/interfaces/media.md)

  产品的特色媒体

* `handle`

  [String!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/string.md)

  产品的handle

* `hasOnlyDefaultVariant`

  [Boolean!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/boolean.md)

  如果该值为 true，则表示该产品只有一种具有默认选项和值的变体

* `id`

  [ID!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/id.md)

  产品ID，通用的唯一标识符

* `images`

  [ImageConnection](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common-objects/objects/image-connection.md)

  与产品相关的图像

* `inCollection`

  [Boolean](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/boolean.md)

  确定产品是否属于指定分类

* `isGiftCard`

  [Boolean!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/boolean.md)

  是否礼品卡商品

* `media`

  [MediaConnection](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common-objects/objects/media-connection.md)

  与产品相关的媒体。这可以包括图像、视频

* `mediaCount`

  [Int!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/int.md)

  与产品关联的媒体总数

* `onlineStorePreviewUrl`

  [URL](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/url.md)

  用于预览在线商店的 URL

* `onlineStoreUrl`

  [URL](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/url.md)

  在线商店中产品的 URL。如果未发布到在线商店，则该值为空

* `options`

  [[ProductOption]](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/products-and-collections/objects/product-option.md)

  产品的选项列表

* `priceRange`

  [ProductPriceRange](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/products-and-collections/objects/product-price-range.md)

  产品的价格范围，格式为小数价格

* `productCategory`

  [ProductCategory](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/products-and-collections/objects/product-category.md)

  商家指定的产品标准类型

* `productType`

  [String](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/string.md)

  商家自定义的一个产品类型

* `publishedAt`

  [Date](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/date.md)

  产品发布到在线商店的日期和时间（采用 ISO 8601 格式）

* `publishedInContext`

  [Boolean!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/boolean.md)

  产品是否在给定的条件中对客户可见

* `resourcePublicationsV2`

  [ResourcePublicationV2Connection](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/apps/objects/resource-publication-v2-connection.md)

  已发布或准备发布的资源列表

* `spu`

  [String](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/string.md)

  产品的SPU码

* `status`

  [ProductStatus!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/products-and-collections/enums/product-status.md)

  产品状态

* `subtitle`

  [String](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/string.md)

  产品摘要

* `tags`

  [[String]](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/string.md)

  产品标签

* `title`

  [String!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/string.md)

  产品标题

* `totalInventory`

  [Int!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/int.md)

  产品的可用库存数量

* `totalVariants`

  [Int!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/int.md)

  产品变体数量

* `tracksInventory`

  [Boolean!](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/boolean.md)

  产品是否启用库存跟踪

* `updatedAt`

  [Date](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/date.md)

  产品最后修改的日期和时间

* `variants`

  [ProductVariantConnection](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/products-and-collections/objects/product-variant-connection.md)

  产品的变体列表

* `vendor`

  [String](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/common/scalars/string.md)

  产品品牌

## Code Example

```graphql
 {
	productByHandle(handle ) 
		 {
			# Product fields
		}
}
```

## Error Handling

关于更多通用错误码说明，参考：[状态码和错误码](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/graph-ql-admin-api/overview.md#status-and-error-codes)。