Oracle Fusion Cloud Customer ExperienceのSales and Fusion ServiceのREST API

添付の処理

このトピックは、RESTリソースに関連付けられた添付の操作に使用できる情報に役立ちます。

タスクやビジネス・プロセスによっては、将来参照するために、文書やイメージ、その他のファイルを添付の形式で格納および保守する必要がある場合があります。添付は、大きなオブジェクト、テキスト、イメージまたはメディア・ファイルの形式で存在する場合があります。通常、Oracle REST APIは、すべてのタイプの添付の操作をサポートしています。

ビジネス要件に基づいて、添付をサポートし、CRUD操作のいずれかを実行するRESTリソースにアクセスできます。予想される結果を得るには、HTTPメソッドを使用して添付を取得および格納する方法を理解する必要があります。また、特定のリソース属性と、リクエストに渡す関連値も把握している必要があります。これらの詳細は、添付のデータ・タイプとその保存ロケーションによって異なります。以降のセクションでは、添付ファイルの操作方法についてもう少し説明します。

ストレージ

Fusion Applicationsでは、次の2つの方法で添付の処理がサポートされています:

同じデータベース表内の列への添付の格納
Oracle WebCenter Contentなどの外部コンテンツ・リポジトリへの添付の格納

添付に対するCRUD操作の実行方法は、添付の格納場所とデータ型によって異なります。次の表は、これらのストレージ・ロケーションについてもう少し理解しやすく、その作業中に考慮すべきいくつかの重要なポイントを示しています。

ストレージのロケーション	キー・ポイント
添付がデータベース表の列に格納されている場合	格納されたコンテンツは、`BLOB`または`CLOB`データ型の添付をサポートするエンクロージャ・リンクの形式でアクセスできます。サポートされるデータ型は、ラージ・オブジェクト、テキストおよびマルチメディアです。
添付が外部コンテンツ・リポジトリに格納されている場合	リポジトリ上のファイルへの参照を含む`FileContents`エンクロージャ・リンクを使用して、ダウンロードを容易にします。添付は子リソースとして格納されます。複数の添付をリスト形式で含めることができます。サポートされているアタッチメント・タイプは、`FILE`、`TEXT`および`URL`です。

添付ファイルの操作方法は、特定のビジネス・オブジェクトをRESTエンドポイントとして使用する方法と、許可されるアクションによって異なります。特に制限がないかぎり、すべてのアタッチメント・リソースはCRUD操作をサポートしています。

REST APIによる添付の処理方法を理解できるように、いくつかの例を見てみましょう。最も頻繁に使用されるメソッドとして、次の項では、GETおよびPOST操作について説明します。

添付の取得

従業員番号1731955の従業員レコードの例を考えてみましょう。そのレコードには、プロファイル写真の表示に使用される添付として写真が含まれています。この例では、コンテンツはデータベースの列に格納されます。 GETリクエストの例を次に示します:

curl -i -u "<username>:<password>" -H "Content-type:application/vnd.oracle.adf.resourceitem+json" -X GET https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/employee/1731955

レスポンスは、次のように表示されます:

{
  "Resources" : {
    "Employees" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
      }, {
        "name" : "Picture",
        "type" : "attachment",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : false,
        "actions" : [ {          
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/octet-stream" ]
        } ]
      } ],
      "item" : {
        "links" : [ {
         ...
        }, {
          "rel" : "enclosure",
"href" : "http://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/employee/1731955/enclosure/Picture",
          "name" : "Picture",
          "kind" : "other"
        } ],
        "actions" : [ {
        } ]
      },
      "links" : [ {
        ...
      } ]
  }
}

レスポンスのリンク・セクションで、データベースに格納されているイメージへの参照がエンクロージャ・リンクとして表示されることがわかります。イメージが子アタッチメント・リソースとして格納されている場合、レスポンスは次のように異なります:

"items": [
        {
            "AttachedDocumentId": 300100548213429,
            "LastUpdateDate": "2021-11-09T03:20:09.640+00:00",
            "LastUpdatedBy": "JDoe",
            "DatatypeCode": "IMAGE",
            "FileName": "Picture.png",
            "DmFolderPath": null,
            "DmDocumentId": "UCMFA00058526",
            "DmVersionNumber": "58442",
            "Url": null,
            "CategoryName": "PROFILE_IMAGE",
            "UserName": "Default Image",
            "Uri": null,
            "FileUrl": "/content/conn/FusionAppsContentRepository/uuid/dDocID:58442?download&XFND_SCHEME_ID=1&XFND_CERT_FP=050B97D1B0F57AC305F88E205CE029181C4A07C8&XFND_RANDOM=-7556731710778165326&XFND_EXPIRES=1636479471368&XFND_SIGNATURE=a0GQlxttK~EVWFAxSwW1XuO0BEgzHYneIjl7R9NcECBJ~4y6TKRBlaHf~C0WHPG9wpm~rpWjpd-tZmGejYBgVmKz~Mx~oM~Fi1ZwAjjPRNxx0uqtmuf6s8XVBUMZgoXk1jG2lIWOv1HIjsGf17xcu1P2WJlGIrYCDRFTgMs5u1ZUGyUcLBNe4X59ty~DrNYPzrXhd2fCZ2koPPL12f2UtXIUClQuGFmxZPxOyWv6WKFzrZyXv4T5hcPNa3oeW7ULMERR-DLy0eDuOVPHF~AeoUUMvNkQYdxENs7qkE9XYgCyLD7iekdNvEL6~quGTbjMsxNYE-JozfVyCv4GsmDTtQ__&Id=58442",
            "UploadedText": null,
            "UploadedFileContentType": "image/png",
            "UploadedFileLength": 157,
            "UploadedFileName": null,
            "ContentRepositoryFileShared": "false",
            "Title": "Picture",
            "Description": "Image description",
            "ErrorStatusCode": null,
            "ErrorStatusMessage": null,
            "CreatedBy": "JDoe",
            "CreationDate": "2021-11-09T03:20:08+00:00",
            "ExpirationDate": null,
            "LastUpdatedByUserName": "John Doe ",
            "CreatedByUserName": " John Doe",
            "AsyncTrackerId": null,
"links": [
                .
                .
                .
                {
                    "rel": "enclosure",
                    "href": " http://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/employee/1731955/ child/ProductGroupAttachments/00020000000EACED0005770800005AF31A4423D40000000EACED0005770800005AF31A4423D3/enclosure/FileContents",
                    "name": "FileContents",
                    "kind": "other"
                },
                
            ]
 }
]

リンク・セクションでは、FileContentsのhrefプロパティに、子リソースとして格納されているアタッチメントをダウンロードするためのリンクが含まれていることがわかります。

添付の作成

添付を作成するには、まず添付のタイプを決定し、必要な情報をPOSTリクエストに渡す必要があります。製品ID 100000011628005を持つ製品カタログ・リソースにイメージを追加する例について考えてみましょう。イメージのbase64エンコード形式を使用して添付を作成する場合は、エンコードされたテキストをリクエスト・ペイロードの一部として含めます。エンコードされたテキストを含むPOSTリクエストの例を次に示します:

curl -i -u "<username>:<password>" -H "Content-type:application/vnd.oracle.adf.resourceitem+json" -X POST https:// servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/setupSalesCatalogs/100000011628005/child/ProductGroupAttachments/ -d '{"Image": "/9j/4AAQSkZJRgABAQEASABIAAD/4QBQRXhpZgAASUkqAAgAAAABAGmHBAABAAAAGgAAAAAAAAABAIaSAgAbAAAALAAAAAAAAABTb2Z0d2FyZTogTWljcm9zb2Z0IE9mZmljZQAA/9sAQwAIBgYHBgUIBwcHCQkICgwUDQwLCwwZEhMPFB0aHx4dGhwcICQuJyAiLCMcHCg3KSwwMTQ0NB8nOT04MjwuMzQy/9sAQwEJCQkMCwwYDQ0YMiEcITIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIy/8AAEQgBaAHgAwEiAAIRAQMRAf/EAB8AAAEFAQEBAQEBAAAAAAAAAAABAgMEBQYHCAkKC//EALUQAAIBAwMCBAMFBQQEAAABfQECAwAEEQUSITFBBhNRYQcicRQygZGhCCNCscEVUtHwJDNiOvQfC/xXWeZLXXIliLcC5T7uf9odq0p42nN2ehwYzhnGYePPG00u2/3HqmaNwFRpIssaujBkYZBHIIrgviveXVjoFpJazyQubjBMbEEjBrpqTUIOR42Ew0sTXjQTs5Ox6DkUZFfMH/AAkOs/8AQTu/+/po/wCEh1n/AKCd3/39NcX9oR/lPqP9T63/AD9X3M+n8ijIr5g/4SHWf+gnd/8Af00f8JDrP/QTu/8Av6aP7Qj/ACh/qfW/5+r7mfT+RRuFfMH/AAkOs/8AQUu/+/prY0f4h6=="}'

レスポンスには、エンクロージャ・リンクとして参照が含まれます:

{
"rel" : "enclosure", 
"href" : "http://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/setupSalesCatalogs/100000011628005/child/ProductGroupAttachments/123456789/enclosure/Image", 
          "name" : "Image", 
          "kind" : "other" 
        }

または、子リソースとして使用可能な添付を作成する場合は、リクエストにいくつかの属性を指定する必要があります。次の表に、添付タイプに基づく必須属性と表示値を示します。

添付タイプ必須の属性と値

添付タイプ	必須の属性と値
ファイル	`"DatatypeCode": "FILE", "CategoryName": "<name of the category>", "FileContents": "encoded file stream"`
自由形式テキスト	`"DatatypeCode":"TEXT" "CategoryName": "<name of the category>", "UploadedText":"Sample freeform text???"`
URL	`"DatatypeCode":"WEB_PAGE" "CategoryName": "<name of the category>", "Url": "<link to the web page/url>"`

ファイル

"DatatypeCode": "FILE",
"CategoryName": "<name of the category>",
"FileContents": "encoded file stream"

自由形式テキスト

"DatatypeCode":"TEXT"
"CategoryName": "<name of the category>",
"UploadedText":"Sample freeform text???"

URL

"DatatypeCode":"WEB_PAGE"
"CategoryName": "<name of the category>",
"Url": "<link to the web page/url>"

製品ID 100000011628005を持つ製品カタログ・リソースにイメージを追加する場合と同じ例を使用して、添付のファイル・タイプとしてイメージを渡す必要がある場合、POSTリクエストを構成する方法を次に示します。

curl -i -u "<username>:<password>" -H "Content-type:application/vnd.oracle.adf.resourceitem+json" -X POST https:// servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/setupSalesCatalogs/100000011628005/child/ProductGroupAttachments/

サンプル・リクエスト本文は次のとおりです:

{
        "DatatypeCode":"FILE",
        "FileName":"Image.png",
        "CategoryName":"CATALOG_IMAGE",
        "Title":"Image",
        "Description":"Image description",
        "FileContents":
        "R0lGODlhEAAQALMAAIuWq6WxwwFGevn9/9Xz//H7/+z6/+77//b9//r///z//////wAAAAAAAAAAAAAAACH5BAEAAAsALAAAAAAQABAAAARKcMlJq7026M1DDUQoih4FAmiqAtM5vqzkGnRNx4t77PyOu4WgMPgjAAiCpFJQKB4Rr5CTMKhaq7/AMcHtcnGSo2JMHoMXqzRmHQEAOw=="
    }

レスポンスは、GETリクエストの例で前述したものと似ています。イメージはエン・クロージャ・リンクの形式でアクセスできます。

"links": [
                .
                .
                .
                {
                    "rel": "enclosure",
                    "href": " 
http://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/setupSalesCatalogs/100000011628005/child/ProductGroupAttachments/00020000000EACED0005770800005AF31A4423D40000000EACED0005770800005AF31A4423D3/enclosure/FileContents",
                    "name": "FileContents",
                    "kind": "other"
                },
                
            ]

添付をダウンロードするには、FileContentsのhrefプロパティに指定されているリンクをクリックします。

参照

製品には、添付をサポートする特定のリソースがある場合があります。その他のガイダンスについては、製品固有のREST APIガイドを参照してください。