AppUsageRecordの冪等性による作成

1. 技術的課題の定義と現状分析

ShopifyのAdmin GraphQL APIでは、appUsageRecordCreateによるアプリ使用記録の作成が可能です。しかし、同じアプリ使用記録が複数回作成されると、誤ってマーチャントに対して二重請求が発生する可能性がありました。これは、開発者やマーチャントにとって大きな課題となります。

2. 具体的な技術的ソリューションの提案

この課題に対する解決策として、Admin GraphQL APIの2023年4月版では、appUsageRecordCreateに冪等性のキー（idempotencyKey）を追加することで、二重請求を防止する機能が導入されました。このキーが提供されると、同一のidempotencyKeyを持つ以前のappUsageRecordCreateのミューテーションと同じレスポンスを返し、新たなレコードを作成せず、マーチャントに再度請求することはありません。

3. 実装手順とコード例

idempotencyKeyを利用するための基本的な実装手順は以下の通りです。

1. idempotencyKeyを生成します。UUIDの利用が推奨されています。
2. 作成するアプリ使用記録のミューテーションにidempotencyKeyを追加します。

mutation {
  appUsageRecordCreate(idempotencyKey: "UUID", input: { 
    description: "使用記録の説明", 
    price: { amount: 10.0, currencyCode: USD } 
  }) { 
    userErrors { 
      field 
      message 
    } 
  } 
}

4. パフォーマンス・コスト分析

idempotencyKeyの導入により、同じアプリ使用記録の二重作成という誤りを防止できます。これにより、マーチャントへの不必要な請求を防ぎ、信頼性の向上に寄与します。また、開発者は安全にアプリ使用記録を作成することが可能となり、開発効率と品質が向上します。

5. 実装時の注意点・ベストプラクティス

idempotencyKeyが提供されない場合、appUsageRecordCreateは過去のAPIバージョンと同様に振る舞い、毎回新しいレコードを作成します。したがって、二重請求を避けるためには、idempotencyKeyの提供が必要です。

6. 次のステップ・発展案

アプリはidempotencyKeyを再利用して異なるショップでappUsageRecordを作成し、マーチャントに請求することが可能です。また、異なるアプリは同じショップで同じidempotencyKeyを使用してもショップに請求できます。これにより、アプリ間での課金管理の柔軟性が向上します。

参考記事: Idempotent creation of AppUsageRecord