SimpleQuery - 簡單查詢 -

查詢和統計資料集內檔案，支援邏輯關係表達方式。

介面說明

請確保在使用該介面前，已充分瞭解Intelligent Media Management產品的收費方式和價格。
調用該介面前，請確保您已通過綁定方式（ CreateBinding ）或者主動索引（ IndexFileMeta 或者 BatchIndexFileMeta ）方式將檔案索引到資料集（Dataset）中。
返回結果僅為樣本，根據工作流程範本配置不同，擷取到的檔案中繼資料資訊的類別和包含的內容均有可能與樣本不同。如果有疑問，請加入DingTalk群進行反饋，DingTalk群號請參見聯絡我們。

使用限制

每次查詢最多返回 100 個檔案資訊。
每次查詢最多返回 2000 條彙總統計資訊。
子查詢條件最大支援設定 100 個。
子查詢嵌套深度最多支援 5 層。

查詢條件樣本

如果要搜尋 JPEG 格式的圖片且圖片尺寸大於 1000 像素，則 Query 填寫樣本如下：

{
  "SubQueries":[
    {
      "Field":"ContentType",
      "Value": "image/jpeg",
      "Operation":"eq"
    },         
    {
      "Field":"ImageWidth",
      "Value":"1000",
      "Operation":"gt"
    }
  ],
  "Operation":"and"
}

如果要搜尋oss://examplebucket/path/中所有包含電視或音響標籤的檔案且該檔案的大小大於 10 MB，則 Query 填寫樣本如下：

說明

這裡電視和音響是同一個檔案的不同標籤，在Labels欄位中以兩個獨立對象的方式存在，請注意和下一個例子的區別。

{
  "SubQueries": [
    {
      "Field": "URI",
      "Value": "oss://examplebucket/path/",
      "Operation": "prefix"
    },
    {
      "Field": "Size",
      "Value": "1048576",
      "Operation": "gt"
    },
    {
      "SubQueries": [
        {
          "Field": "Labels.LabelName",
          "Value": "電視",
          "Operation": "eq"
        },
        {
          "Field": "Labels.LabelName",
          "Value": "音響",
          "Operation": "eq"
        }
      ],
      "Operation": "or"
    }
  ],
  "Operation": "and"
}

如果要排除人臉資訊中有一個 36 歲以上的男性的檔案，則 Query 填寫樣本如下：

說明

和上一個例子不同的是，這裡要求某一個人臉同時滿足 36 歲以上、男性兩個條件，這和一張圖片中有多個人臉，其中某個是男性，而其中另一個是 36 歲以上這個需求是不同的。在該請求中，需要使用nested查詢實現條件在同一個元素內同時滿足的限制。

{
	"Operation": "not",
	"SubQueries": [{
		"Operation": "nested",
		"SubQueries": [{
			"Operation": "and",
			"SubQueries": [{
				"Field": "Figures.Age",
				"Operation": "gt",
				"Value": "36"
			}, {
				"Field": "Figures.Gender",
				"Operation": "eq",
				"Value": "male"
			}]
		}]
	}]
}

如果要搜尋 JPEG 格式的圖片且圖片存在自訂標籤和系統標籤，則 Query 填寫樣本如下：

{
  "SubQueries":[
    {
      "Field":"ContentType",
      "Value": "image/jpeg",
      "Operation":"eq"
    },         
    {
      "Field":"CustomLabels.test",
      "Operation":"exist"
    },         
    {
      "Field":"Labels.LabelName",
      "Operation":"exist"
    }
  ],
  "Operation":"and"
}

結合以上搜尋條件，您還可以通過彙總操作實現不同資料的統計和分析，例如計算符合搜尋條件的所有檔案的大小總和、數量、平均值或者最值，統計所有符合搜尋條件圖片的尺寸分布情況。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

imm:SimpleQuery

list

*Dataset

acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}/dataset/{#DatasetName}

無

請求參數

名稱	類型	必填	描述	樣本值
NextToken	string	否	當檔案總數大於設定的 MaxResults 時，用於翻頁的 token。從 NextToken 開始按字典序返迴文件資訊列表。第一次調用此介面時，設定為空白。	MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==
MaxResults	integer	否	不傳 Aggregations 參數查詢檔案時，表示返迴文件的最大個數，取值範圍為 0~100。傳 Aggregations 參數進行彙總統計時，表示返回分組的最大個數，取值範圍為 0~2000。不設定此參數或者設定為 0 時，則預設值為 100。	10
ProjectName	string	是	專案名稱，擷取方式請參見建立專案。	test-project
DatasetName	string	是	資料集名稱，擷取方式請參見建立資料集。	test-dataset
Query	SimpleQuery	否	簡單查詢條件。請點擊左側連結查看詳情。
Sort	string	否	排序欄位列表。請參考欄位和操作符的支援列表。說明多個排序欄位可使用半形逗號（,）分隔，例如：Size,Filename。最多可設定 5 個排序欄位。排序欄位順序即為排序優先順序順序。	Size,Filename
Order	string	否	排序欄位的排序方式。取值如下： asc：升序 desc（預設）：降序說明多個排序方式可使用半形逗號（,）分隔，例如：asc,desc。排序方式不可多於排序欄位，即參數 Order 的元素數量需小於等於參數 Sort 的元素數量。例如 Sort 取值為 Size,Filename 時，Order 可取值為"asc,desc"。排序方式少於排序欄位時，未排序的欄位預設取值 desc。例如 Sort 取值為 Size,Filename，Order 取值為 asc 時，Filename 預設排序方式為 desc，即降序排列。	asc,desc
Aggregations	array<object>	否	彙總欄位資訊列表。重要當您使用彙總查詢時，僅返回彙總結果，不再返回匹配到的元資訊列表。
	object	否	彙總欄位資訊的結構體。
Field	string	否	欄位名稱。關於支援的欄位，請參見欄位和操作符的支援列表。	Size
Operation	string	否	彙總欄位的操作符。枚舉值： average : 平均數 min : 最小值 max : 最大值 count : 計數 distinct : 去重計數 sum : 求和 group : 分組計數，按照分組計數結果從高到低排序	sum
WithFields	array	否	僅返回特定欄位的值，而不是全部已有的元資訊欄位。可用於降低返回的結構體大小。不填或留空則返回所有欄位。
	string	否	需要返回欄位的欄位名。支援 File 中列舉支援的欄位名。	Filename
WithoutTotalHits	boolean	否	是否返回命中記錄總數 true 不返回 TotalHits 欄位 false 返回 TotalHits 欄位

返回參數

名稱	類型	描述	樣本值
	object	響應結構體。
NextToken	string	當檔案總數大於設定的 MaxResults 時，用於翻頁的 token。下一次列出檔案資訊時以此值為 NextToken，將未返回的結果返回。當檔案未全部返回時，此參數才有值。	MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==
RequestId	string	請求 ID。	2C5C1E0F-D8B8-4DA0-8127-EC32C771****
Files	array	檔案資訊列表。僅在請求的 Aggregations 為空白時返回。
	File	檔案資訊的結構體。
Aggregations	array<object>	彙總欄位資訊列表。僅在請求的 Aggregations 不為空白時返回。
	array<object>	彙總欄位資訊結構體。
Field	string	彙總欄位名稱。	Size
Operation	string	彙總欄位的彙總操作符。	sum
Value	number	彙總的統計結果。	200
Groups	array<object>	分組彙總的結果清單。僅在請求的 Aggregations 中存在 group 類型的 Operation 時才會返回。
	object	分組彙總的結果。
Value	string	分組彙總的值。	100
Count	integer	分組彙總的總個數。	5
TotalHits	integer	命中的記錄數。	10

樣本

正常返回樣本

JSON格式

{
  "NextToken": "MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==",
  "RequestId": "2C5C1E0F-D8B8-4DA0-8127-EC32C771****",
  "Files": [
    {
      "OwnerId": "102321002467****",
      "ProjectName": "test-project",
      "DatasetName": "test-dataset",
      "ObjectType": "file",
      "ObjectId": "75d5de2c50754e3dadd5c35dbca5f9949369e37eb342a73821f690c94c36c7f7",
      "UpdateTime": "2021-06-29T14:50:13.011643661+08:00",
      "CreateTime": "2021-06-29T14:50:13.011643661+08:00",
      "URI": "oss://test-bucket/test-object.jpg",
      "OSSURI": "oss://examplebucket/sampleobject.jpg",
      "Filename": "sampleobject.jpg",
      "MediaType": "image",
      "ContentType": "image/jpeg",
      "Size": 1000,
      "FileHash": "1d9c280a7c4f67f7ef873e28449dbe17",
      "FileModifiedTime": "2021-06-29T14:50:13.011643661+08:00",
      "FileCreateTime": "2021-06-29T14:50:13.011643661+08:00",
      "FileAccessTime": "2021-06-29T14:50:13.011643661+08:00",
      "ProduceTime": "2021-06-29T14:50:13.011643661+08:00",
      "LatLong": "30.134390,120.074997",
      "Timezone": "\"\"",
      "Addresses": [
        {
          "Language": "zh-Hans",
          "AddressLine": "中國浙江省杭州市餘杭區文一西路969號",
          "Country": "中國",
          "Province": "浙江省",
          "City": "杭州市",
          "District": "餘杭區",
          "Township": "文一西路"
        }
      ],
      "TravelClusterId": "-",
      "Orientation": 0,
      "Figures": [
        {
          "FigureId": "868a9e74-cde5-4c7a-9013-28bb984****",
          "FigureConfidence": 1,
          "FigureClusterId": "Cluster-dbe72fec-b84c-4ab6-885b-3678e64****",
          "FigureClusterConfidence": 1,
          "FigureType": "face",
          "Age": 29,
          "AgeSD": 5,
          "Gender": "female",
          "GenderConfidence": 1,
          "Emotion": "happiness",
          "EmotionConfidence": 0.70784568786621,
          "FaceQuality": 0.960875928401947,
          "Boundary": {
            "Width": 200,
            "Height": 300,
            "Left": 10,
            "Top": 30,
            "Polygon": [
              {
                "X": 10,
                "Y": 10
              }
            ]
          },
          "Mouth": "close",
          "MouthConfidence": 1,
          "Beard": "none",
          "BeardConfidence": 1,
          "Hat": "none",
          "HatConfidence": 1,
          "Mask": "none",
          "MaskConfidence": 1,
          "Glasses": "none",
          "GlassesConfidence": 0.8,
          "Sharpness": 0.7,
          "Attractive": 0.96,
          "HeadPose": {
            "Pitch": 18.385589599609375,
            "Roll": 4.204030513763428,
            "Yaw": 2.4945924282073975
          }
        }
      ],
      "FigureCount": 10,
      "Labels": [
        {
          "Language": "zh-Hans",
          "LabelName": "",
          "LabelLevel": 2,
          "LabelConfidence": 0.95,
          "ParentLabelName": "",
          "CentricScore": 0.877,
          "LabelAlias": "",
          "Clips": [
            {
              "TimeRange": [
                0
              ]
            }
          ]
        }
      ],
      "Title": "test",
      "ImageWidth": 270,
      "ImageHeight": 500,
      "EXIF": "{\"Compression\":{\"value\":\"6\"},\"DateTime\":{\"value\":\"2020:08:19 17:11:11\"}}",
      "ImageScore": {
        "OverallQualityScore": 0.736
      },
      "CroppingSuggestions": [
        {
          "AspectRatio": "2:3",
          "Confidence": 0.742,
          "Boundary": {
            "Width": 200,
            "Height": 300,
            "Left": 10,
            "Top": 30,
            "Polygon": [
              {
                "X": 10,
                "Y": 10
              }
            ]
          }
        }
      ],
      "OCRContents": [
        {
          "Language": "zh-hans",
          "Contents": "歡迎使用Intelligent Media Management",
          "Confidence": 0.8254936695098877,
          "Boundary": {
            "Width": 200,
            "Height": 300,
            "Left": 10,
            "Top": 30,
            "Polygon": [
              {
                "X": 10,
                "Y": 10
              }
            ]
          }
        }
      ],
      "VideoWidth": 1080,
      "VideoHeight": 1920,
      "VideoStreams": [
        {
          "Index": 0,
          "Language": "en",
          "CodecName": "h264",
          "CodecLongName": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
          "Profile": "High",
          "CodecTimeBase": "1373627/83160000",
          "CodecTagString": "avc1",
          "CodecTag": "0x31637661",
          "Width": 1280,
          "Height": 720,
          "HasBFrames": 2,
          "SampleAspectRatio": "1:1",
          "DisplayAspectRatio": "16:9",
          "PixelFormat": "yuv420p",
          "Level": 40,
          "FrameRate": "25/1",
          "AverageFrameRate": "25/1",
          "TimeBase": "1/12800",
          "StartTime": 0,
          "Duration": 22.88,
          "Bitrate": 5407765,
          "FrameCount": 572,
          "Rotate": "90",
          "BitDepth": 8,
          "ColorSpace": "bt709",
          "ColorRange": "tv",
          "ColorTransfer": "bt709",
          "ColorPrimaries": "bt709"
        }
      ],
      "Subtitles": [
        {
          "Index": 2,
          "Language": "en",
          "CodecName": "mov_text",
          "CodecLongName": "MOV text",
          "CodecTagString": "tx3g",
          "CodecTag": "0x67337874",
          "StartTime": 0,
          "Duration": 71.378,
          "Bitrate": 74,
          "Content": "歡迎",
          "Width": 600,
          "Height": 30
        }
      ],
      "AudioStreams": [
        {
          "Index": 1,
          "Language": "en",
          "CodecName": "aac",
          "CodecLongName": "AAC (Advanced Audio Coding)",
          "CodecTimeBase": "1/44100",
          "CodecTagString": "mp4a",
          "CodecTag": "0x6134706d",
          "TimeBase": "1/48000",
          "StartTime": 0.0235,
          "Duration": 3.690667,
          "Bitrate": 320087,
          "FrameCount": 173,
          "Lyric": "test",
          "SampleFormat": "fltp",
          "SampleRate": 48000,
          "Channels": 2,
          "ChannelLayout": "stereo"
        }
      ],
      "Artist": "Jane",
      "AlbumArtist": "Jane",
      "AudioCovers": [
        {
          "ImageWidth": 500,
          "ImageHeight": 820,
          "EXIF": "{\"FileSize\":{\"value\":\"29304\"},\"Format\":{\"value\":\"jpg\"}}",
          "ImageScore": {
            "OverallQualityScore": 0.736
          },
          "CroppingSuggestions": [
            {
              "AspectRatio": "2:3",
              "Confidence": 0.742
            }
          ],
          "OCRContents": [
            {
              "Language": "zh-hans",
              "Contents": "歡迎使用Intelligent Media Management",
              "Confidence": 0.8254936695098877
            }
          ]
        }
      ],
      "Composer": "Jane",
      "Performer": "Jane",
      "Language": "eng",
      "Album": "FirstAlbum",
      "PageCount": 5,
      "ETag": "\"1D9C280A7C4F67F7EF873E28449****\"",
      "CacheControl": "no-cache",
      "ContentDisposition": "attachment; filename =test.jpg",
      "ContentEncoding": "UTF-8",
      "ContentLanguage": "zh-CN",
      "AccessControlAllowOrigin": "https://aliyundoc.com",
      "AccessControlRequestMethod": "PUT",
      "ServerSideEncryptionCustomerAlgorithm": "SM4",
      "ServerSideEncryption": "AES256",
      "ServerSideDataEncryption": "SM4",
      "ServerSideEncryptionKeyId": "9468da86-3509-4f8d-a61e-6eab1eac****",
      "OSSStorageClass": "Standard",
      "OSSCRC64": "559890638950338001",
      "ObjectACL": "default",
      "ContentMd5": "HZwoCnxPZ/fvhz4oRJ2+Fw==",
      "OSSUserMeta": {
        "key": "val"
      },
      "OSSTaggingCount": 2,
      "OSSTagging": {
        "key": "val"
      },
      "OSSExpiration": "2120-01-01T12:00:00.000Z",
      "OSSVersionId": "CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****",
      "OSSDeleteMarker": "CAEQMhiBgIDXiaaB0BYiIGQzYmRkZGUxMTM1ZDRjOTZhNjk4YjRjMTAyZjhl****",
      "OSSObjectType": "Normal",
      "CustomId": "\t\nmember-image-id-0001",
      "CustomLabels": {
        "MemberName": "Tim",
        "Enabled": "True",
        "ItemCount": "10"
      },
      "StreamCount": 1,
      "ProgramCount": 1,
      "FormatName": "mov",
      "FormatLongName": "QuickTime / MOV",
      "StartTime": 0,
      "Bitrate": 13091201,
      "Duration": 15.263,
      "SemanticTypes": [
        "content"
      ],
      "Elements": [
        {
          "ElementContents": [
            {
              "Type": "text",
              "Content": "文本片段",
              "URL": "http://aliyun.com",
              "TimeRange": [
                500
              ]
            }
          ],
          "ObjectId": "id1",
          "ElementType": "title - 標題； image - 圖片 ； table - 表格 ； narrative-text - 本文",
          "SemanticSimilarity": 0.8,
          "ElementRelations": [
            {
              "Type": "child，parent",
              "ObjectId": "id1"
            }
          ]
        }
      ],
      "SceneElements": [
        {
          "TimeRange": [
            100
          ],
          "FrameTimes": [
            30
          ],
          "VideoStreamIndex": 0,
          "Labels": [
            {
              "Language": "zh-Hans",
              "LabelName": "",
              "LabelLevel": 2,
              "LabelConfidence": 0.95,
              "ParentLabelName": "",
              "CentricScore": 0.877,
              "LabelAlias": "",
              "Clips": [
                {
                  "TimeRange": [
                    0
                  ]
                }
              ]
            }
          ]
        }
      ],
      "OCRTexts": "阿里雲IMM",
      "Reason": "[InternalError] The request has been failed due to some unknown error. status: 500, requestId: CC5ACFBD-BB7A-496D-A9D6-****",
      "ObjectStatus": "Indexed",
      "Insights": {
        "Video": {
          "Description": "無。",
          "Caption": "視頻中展示了兩個不同情境：一個是靜止的白色盤子、黑色瓶子和透明玻璃杯，另一個是手拿著標有“YEZOLU”的洗髮水瓶在浴室中緩慢上移。"
        },
        "Image": {
          "Caption": "無。",
          "Description": "圖片中有一人，穿著深色西裝外套，內搭白色襯衫。背景為漸層的淺藍色至灰色。"
        }
      }
    }
  ],
  "Aggregations": [
    {
      "Field": "Size",
      "Operation": "sum",
      "Value": 200,
      "Groups": [
        {
          "Value": "100",
          "Count": 5
        }
      ]
    }
  ],
  "TotalHits": 10
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。