SAP Public Cloud: PurchaseOrderItemをV2からV4へ変更する方法と注意点

## 1. はじめに
この記事は [SAP Advent Calendar 2024](https://adventar.org/calendars/10423) の12月6日分の記事として執筆しています。

今回はSAP Public CloudのOData APIで非推奨になったV2をV4に変更する際に手間取った点等連係させていただきます。本記事では、私が実際に変更したAPI(PurchaseOrderItem)のV2とV4の違い、移行する際に発生した不具合や注意点を記載しております。

## 2.バージョンアップに至る経緯
SAPのAPI「A_PurchaseOrderItem」(V2)を使用しているアプリケーションで不具合が発生しました。購買発注の勘定設定(_PurOrdAccountAssignment)にWBSElementを設定しているにもかかわらず、「WBS要素を指定してください」というエラーが出る不具合です。

### 原因の特定とWBSElementについて
WBSElementには`WBSElementInternalID`・`WBSElement`・`WBSElementExternalID`の3種類存在します。`WBSElementExternalID`がキーの役割を果たし、紐づけ等に利用されます。
V2の方はWBSElementInternalID・WBSElement・WBSElementExternalIDすべて存在(24件。勘定設定の階層)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3940987/e13b629c-e471-821c-2566-14330e3c0950.png)
V4の方にはWBSElementInternalID(8桁)・WBSElementExternalID(24桁)のみ存在(勘定設定の階層)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3940987/4f4188f6-5394-d3f0-6ca8-ec0e38213af1.png)
PurchaseOrderItemを用いたCDSViewの「WBSElementExternalID」を「WBSElement」に設定していたため発生したり、CDSViewで取得していたWBSが非推奨だったため発生した不具合のようです。※最新はWBSElementExternalID_2
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3940987/0424b5ae-6a5b-352d-e28c-7c837b7d4cc8.png)
原因はともあれ、V2は非推奨なのでV4へ変更することとなりました。

## 3. V2とV4の主な違い

### API仕様の変更点
V2とV4では、いくつかの重要な仕様変更があります。
- **エンドポイント**
使用するエンドポイントが違います。

- **項目**
項目の名称が異なる項目があります。また、V2では非推奨な項目が存在する場合があり、非推奨を使用することでデータの不整合が起こる可能性があります

- **レスポンス形式**
V4では、エラーメッセージがより詳細に提供されるようになり、デバッグやトラブルシューティングが容易になったそうです

## 4. V2からV4へ修正点

#### エンドポイント
  V2とV4ではそれぞれ下記のエンドポイントを使用します。
  ```python
  # V2
  url = "https://{host}:{port}/sap/opu/odata/sap/API_PURCHASEORDER_PROCESS_SRV/A_PurchaseOrderItem"
  
  # V4
  url = "https://{host}:{port}/sap/opu/odata4/sap/api_purchaseorder_2/srvd_a2x/sap/purchaseorder/0001/PurchaseOrder(PurchaseOrder='XXXXXX')/_PurchaseOrderItem"
  ```

V4のPurchaseOrderItemでは、エンドポイントにPurchaseOrderを指定する必要があるようです。

#### パラメータの主な変更点
V4ではパラメータ名等が変更されているケースがあります。変更中に下記が確認されました。
  
| エンティティ | 変更点 |V2 | V4 |
|:-----------:|:------------|:------------:|:------------:|
| 数量系     |""の有無 | "10000"        | 10000         |
| 日付系     | 時間設定の有無| "2024-12-01T00:00:00"| "2024-12-01"       |
| 住所系     |階層の有無 | 階層なし        | _DeliveryAddress": {…|
| 住所系     | 名称の変更| DeliveryAddressName        | OrganizationName1|
| 明細       | 自動採番か否か |   (自動採番で記載不要)     | "PurchaseOrderItem": "10"  |
| 階層       | 名称の変更| to_AccountAssignment        | _PurOrdAccountAssignment   |

階層の名称に関しては、Business Accelerator Hubを確認するとでてきます。
数量や日付、明細の設定に関しては他のAPIでも変わっていそうな気はします。

#### 実際に使用したパラメータ

```json:V2
{
    "PurchaseOrder": "1234567890",
    "Material": "",
    "MaterialGroup": "ABC1",    
    "StorageLocation": "A001",
    "PurchaseOrderItemText": "Text備考",
    "NetPriceAmount": "10000",
    "DocumentCurrency": "JPY",
    "OrderQuantity": "1",
    "PurchaseOrderQuantityUnit": "式",
    "Plant": "1234",
    "AccountAssignmentCategory": "P",
    "DeliveryAddressName": "住所A",
    "DeliveryAddressName2": "住所B",
    "DeliveryAddressFullName": "住所名",
    "DeliveryAddressStreetName": "",
    "DeliveryAddressHouseNumber": "",
    "DeliveryAddressCityName": "",
    "DeliveryAddressPostalCode": "123-4567",
    "DeliveryAddressRegion": "13",
    "DeliveryAddressCountry": "JP",
    "to_AccountAssignment": [
        {
            "PurchaseOrder": "1234567890",
            "WBSElement": "01234567",
            "AccountAssignmentNumber": "1"
        }
    ],
    "to_ScheduleLine": [
        {
            "DelivDateCategory": "1",
            "ScheduleLineDeliveryDate": "2024-12-01T00:00:00",
            "SchedLineStscDeliveryDate": "2024-12-01T00:00:00"
        }
    ],
    "to_PurchaseOrderItemNote": [
        {
            "PlainLongText": "明細テキスト",
            "Language": "JA",
            "TextObjectType": "F01"
        }
    ]
}
```
  
```json:V4
{
    "PurchaseOrder": "1234567890",
    "PurchaseOrderItem": "10",
    "Material": "",
    "MaterialGroup": "ABC1",    
    "StorageLocation": "A001",
    "PurchaseOrderItemText": "Text備考",
    "NetPriceAmount": 10000,
    "DocumentCurrency": "JPY",
    "OrderQuantity": 1,
    "PurchaseOrderQuantityUnit": "式",
    "Plant": "1234",
    "AccountAssignmentCategory": "P",
    "_DeliveryAddress": {
        "OrganizationName1": "住所A",
        "OrganizationName2": "住所B",
        "AddresseeFullName": "住所名",
        "StreetName": "",
        "HouseNumber": "",
        "CityName": "",
        "PostalCode": "123-4567",
        "Region": "13",
        "Country": "JP"
    },
    "_PurOrdAccountAssignment": [
        {
            "PurchaseOrder": "1234567890",
            "PurchaseOrderItem": "10",
            "WBSElementInternalID": "01234567",
            "AccountAssignmentNumber": "1"
        }
    ],
    "_PurchaseOrderScheduleLineTP": [
        {
            "DelivDateCategory": "1",
            "ScheduleLineDeliveryDate": "2024-12-01",
            "SchedLineStscDeliveryDate": "2024-12-01"
        }
    ],
    "_PurchaseOrderItemNote": [
        {
            "PlainLongText": "明細テキスト",
            "Language": "JA",
            "TextObjectType": "F01"
        }
    ]
}
```



## 5.変更するにあたり遭遇した不具合と対処(2024/12/06時点)
- **500 Internal Server Error**
一見サーバー側で問題が起きている一時的なエラーに見えますが、パラメーターが不正で確認されました。ちなみにこれは明細を設定せず流した場合に出たもので、明細を設定することで正常に動作します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3940987/bf3dde1f-07e2-3874-bec9-6ee1ab960b48.png)

- **201 Created？？**
一見データが作成されているように見えますが、作成されていないケースです。
見分け方は**ResponseのPurchaseOrderが空文字**であること。ちなみに現状確認されたケースは、「存在しない購買発注番号を指定した場合」、「購買発注明細がすべて論理削除されている場合」です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3940987/1e178b06-f20a-54d8-1a61-9e046b1373e6.png)

修正が11月下旬、記事執筆が11月末だったのですが、投稿前(2024/12/6)の最終確認の段階でエラーの場合のメッセージが11月時点より返ってくるような気がします。ただ、上記事象は2024/12時点でも確認されました。おそらくV4がリリースからの日が浅いために上記の事象が発生しているのだと考えられます。

- **正しいエンティティを流すコツ**
基本的に、S4HANACloudの画面上から登録できるデータはAPIでも登録できるはずです。
また、ヘルプポータルに必須項目の有無等の記載もありますので参考にしてみてください。(下にリンクあります)

## 6. まとめ

SAP Public Cloud EditionでPurchaseOrderItemのODataAPIをV2からV4へのバージョンアップする際に苦労した点を連携させていただきました。PurchaseOrderItem以外でも発生しうる不具合で、バージョンアップして日が浅いと同事象が確認されると考えられます。これらの情報が役に立つと嬉しいです。

## 7. 参考資料
- [PURCHASEORDER_0001 overview](https://api.sap.com/api/CE_PURCHASEORDER_0001/overview)
- [SAP Help Portal:Entities for PurchaseOrder Item](https://help.sap.com/docs/SAP_S4HANA_CLOUD/bb9f1469daf04bd894ab2167f8132a1a/7db5bf21475b4219a28b2bbd67055d2a.html?locale=en-US)
- [SAP Help Portal:Purchase Order (OData V4)](https://help.sap.com/docs/SAP_S4HANA_CLOUD/bb9f1469daf04bd894ab2167f8132a1a/c89eec80ec2043d980cb7b8c89e0a00a.html?locale=en-US)