どっぷりハマって調べまくって、結局解決策はここしか見つからなかった。。。。
端的に解決方法をメモっときます。
referenceDocumentUri
Shopify GraphQLのリファレンスでは、英語にしても日本語に翻訳してもさっぱり意味不明だったけど、上記のコミュニティでやっと分かった。
でも、何でリファレンスにはそうはっきり書いていないのか、謎すぎる。
referenceDocumentUriは、Shopifyにアクセスするアプリのidを指定します。
自身のプログラムからShopifyにgraphQL APIでアクセスするためにShopify管理画面でアプリを作成してアクセス権を登録していたと思います。
そのアプリのidです！
postmanで実行するときは、以下でidを確認できます。
query {
currentAppInstallation{
app{
id
}
}
}
ちなみに、リファレンスにはreferenceDocumentUriとして、次のように書いてあります。
A freeform URI that represents why the inventory change happened. This can be the entity adjusting inventory quantities or the Shopify resource that's associated with the inventory adjustment. For example, a unit in a draft order might have been previously reserved, and a merchant later creates an order from the draft order. In this case, the referenceDocumentUri for the inventory adjustment is a URI referencing the order ID.
日本語に翻訳すると、以下になります。(Google翻訳)
在庫変更が発生した理由を表す自由形式の URI。これは、在庫数量を調整するエンティティ、または在庫調整に関連付けられた Shopify リソースにすることができます。たとえば、下書き注文のユニットが以前に予約されており、販売者が後から下書き注文から注文を作成する場合があります。この場合、在庫調整のreferenceDocumentUriは注文IDを参照するURIとなります。
リファレンスのサンプルコードでは、なんか適当なURIが書いてありますが、これを見ても何を指定していいかさっぱりです。
上記サンプルのようにURIっぽいものを適当に書くと、「URIが無効だ("The specified reference document is invalid.")」と怒られます。
ledgerDocumentUri
さらに謎だったのが、ledgerDocumentUriです。
A freeform URI that represents what changed the inventory quantities. A Shopify global ID isn't an accepted value. For example, specifying "gid://shopify/Order/123" would return an error. This field is required for a move of all quantity names except available. The field ledgerDocumentUri isn't supported for use with an available quantity name.
日本語訳にすると、以下です。
在庫数量の変更内容を表す自由形式の URI。 Shopify グローバル ID は受け入れられる値ではありません。たとえば、「gid://shopify/Order/123」を指定するとエラーが返されます。このフィールドは、使用可能なものを除くすべての数量名の移動に必要です。フィールドledgerDocumentUriは、利用可能な数量名での使用はサポートされていません。
"quantity name"とは、Shopifyで管理している在庫種類です。
例えば、「販売可能」「破損」「品質管理」など8つほどあります。
Inventory Statusというステータスの名前です。
こうした在庫管理をするときに指定しろよ的なニュアンスは伝わったのですが、何を指定すればいいのやら。。。
ちなみに、Inventory Statusが "available"(販売可能)の時は、nullを指定します。
それ以外のInventory Statusで在庫を登録する際に何かしらのURIを指定することになります。
自由形式のURIってなに？
先にリンクしたコミュニティでも、"uri://example.com/some/external/reference"と適当に設定しても動くけど、解せぬ、と回答者が言っている通り、"uri://example.com/some/external/reference"と指定しても本当に正常終了します。
何のために、、、は、もう少し勉強が必要そうです。
知ってる人、教えて。
以下のようにledgerDocumentUriで適当なURLでも正常終了します。
mutation inventoryAdjustQuantities{
inventoryAdjustQuantities(input: {
name: "quality_control",
reason: "quality_control",
changes:[
{
inventoryItemId: "gid://shopify/InventoryItem/12345678901234",
delta: 5,
locationId: "gid://shopify/Location/11111111111"
ledgerDocumentUri: "uri://example.com/some/external/reference"
}
]
}) {
inventoryAdjustmentGroup{
changes{
item{
variant{
inventoryQuantity
}
}
}
}
userErrors{
code
field
message
}
}
}
終わり
Google検索でそれぞれの単語を検索しても数件しかヒットしなくて、有益な情報がコミュニティの回答（しかも結局は回答者も解せぬとコメント）しか探しきれなかったので、取り急ぎ記事にしました。
なんか新情報あったら、更新します。