Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update contract for anomaly detector #12487

Merged
merged 13 commits into from
Feb 9, 2021
Merged

Update contract for anomaly detector #12487

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
df9d08d
update contract for anomaly detector
Jan 19, 2021
696a311
make severity optional
Jan 19, 2021
6913db3
contract update
Jan 20, 2021
a7fc832
update according to PR
Jan 21, 2021
9d71cd0
update values
Jan 22, 2021
37f0a8c
update
Jan 22, 2021
ea9e4a6
prettier fix
Jan 26, 2021
2b8023e
split the PR into two parts, this pr adds two enum values into the gr…
Feb 5, 2021
bc8261b
change preview to stable
Feb 5, 2021
98e62a3
update to stable version
Feb 7, 2021
d61813c
fix build failure
Feb 8, 2021
687a6fb
update
Feb 9, 2021
b86618a
update
Feb 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 107 additions & 29 deletions specification/cognitiveservices/data-plane/AnomalyDetector/preview/v1.0/AnomalyDetector.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@
},
"TimeGranularity": {
"type": "string",
"description": "Can only be one of yearly, monthly, weekly, daily, hourly, minutely or secondly. Granularity is used for verify whether input series is valid.",
"description": "Optional argument, can be one of yearly, monthly, weekly, daily, hourly, minutely, secondly or microsecond. If granularity is present in the request, it will be used to verify whether input series is valid and to impute missing values.",
"x-nullable": false,
"x-ms-enum": {
"name": "TimeGranularity",
Expand Down Expand Up @@ -216,6 +216,9 @@
{
"name": "perSecond",
"value": "secondly"
},
{
"value": "microsecond"
}
]
},
Expand All @@ -226,9 +229,65 @@
"daily",
"hourly",
"minutely",
"secondly"
"secondly",
"microsecond"
jhendrixMSFT marked this conversation as resolved.
Show resolved Hide resolved
]
},
"ImputeMode": {
"type": "string",
"description": "Can be one of auto, previous, linear, fixed, zero or notFill.",
"x-nullable": false,
"x-ms-enum": {
"name": "ImputeMode",
"modelAsString": false,
"values": [
{
"value": "auto"
},
{
"value": "previous"
},
{
"value": "linear"
},
{
"value": "fixed"
},
{
"value": "zero"
},
{
"value": "notFill"
}
]
},
"enum": [
"auto",
"previous",
"linear",
"fixed",
"zero",
"notFill"
]
},
"ImputeStrategy": {
"type": "object",
"required": [
"imputeMode"
],
"properties": {
"imputeMode": {
"$ref": "#/definitions/ImputeMode",
"description": "The method that is used to impute missing values in the given time series."
},
"imputeValue": {
"type": "number",
"format":"float",
"x-nullable": false,
"description": "Optional argument, if imputeMode is set to 'fixed', then this value is used to impute missing values."
}
}
},
"CustomInterval": {
"type": "integer",
"format": "int32",
Expand All @@ -238,7 +297,6 @@
"DetectRequest": {
"type": "object",
"required": [
"granularity",
guinao marked this conversation as resolved.
Show resolved Hide resolved
"series"
],
"properties": {
Expand Down Expand Up @@ -270,20 +328,23 @@
"type": "integer",
"format": "int32",
"description": "Optional argument, advanced model parameter, between 0-99, the lower the value is, the larger the margin value will be which means less anomalies will be accepted."
},
"imputeStrategy": {
"$ref":"#/definitions/ImputeStrategy",
"description": "Optional argument, indicates how to impute the missing values in the series."
}
}
},
"TimeSeriesPoint": {
"type": "object",
"required": [
"timestamp",
"value"
],
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp of a data point (ISO8601 format)."
"description": "Optional argument, timestamp of a data point (ISO8601 format)."
},
"value": {
"type": "number",
Expand All @@ -294,123 +355,142 @@
},
"EntireDetectResponse": {
"type": "object",
"required": [
"expectedValues",
"isAnomaly",
"isNegativeAnomaly",
"isPositiveAnomaly",
"lowerMargins",
"period",
"upperMargins"
],
"properties": {
"period": {
"type": "integer",
"format": "int32",
"readOnly": true,
"description": "Frequency extracted from the series, zero means no recurrent pattern has been found."
},
"expectedValues": {
"type": "array",
"readOnly": true,
"description": "ExpectedValues contain expected value for each input point. The index of the array is consistent with the input series.",
"items": {
"type": "number",
"format": "float",
"readOnly": true,
"x-nullable": false
}
},
"upperMargins": {
"type": "array",
"readOnly": true,
"description": "UpperMargins contain upper margin of each input point. UpperMargin is used to calculate upperBoundary, which equals to expectedValue + (100 - marginScale)*upperMargin. Anomalies in response can be filtered by upperBoundary and lowerBoundary. By adjusting marginScale value, less significant anomalies can be filtered in client side. The index of the array is consistent with the input series.",
"items": {
"type": "number",
"format": "float",
"readOnly": true,
"x-nullable": false
}
},
"lowerMargins": {
"type": "array",
"readOnly": true,
"description": "LowerMargins contain lower margin of each input point. LowerMargin is used to calculate lowerBoundary, which equals to expectedValue - (100 - marginScale)*lowerMargin. Points between the boundary can be marked as normal ones in client side. The index of the array is consistent with the input series.",
"items": {
"type": "number",
"format": "float",
"readOnly": true,
"x-nullable": false
}
},
"isAnomaly": {
"type": "array",
"readOnly": true,
"description": "IsAnomaly contains anomaly properties for each input point. True means an anomaly either negative or positive has been detected. The index of the array is consistent with the input series.",
"items": {
"type": "boolean",
"readOnly": true,
"x-nullable": false
}
},
"isNegativeAnomaly": {
"type": "array",
"readOnly": true,
"description": "IsNegativeAnomaly contains anomaly status in negative direction for each input point. True means a negative anomaly has been detected. A negative anomaly means the point is detected as an anomaly and its real value is smaller than the expected one. The index of the array is consistent with the input series.",
"items": {
"type": "boolean",
"readOnly": true,
"x-nullable": false
}
},
"isPositiveAnomaly": {
"type": "array",
"readOnly": true,
"description": "IsPositiveAnomaly contain anomaly status in positive direction for each input point. True means a positive anomaly has been detected. A positive anomaly means the point is detected as an anomaly and its real value is larger than the expected one. The index of the array is consistent with the input series.",
"items": {
"type": "boolean",
"readOnly": true,
"x-nullable": false
}
},
"severity": {
"type": "array",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is a value returned by your service, consider marking it as readOnly: true

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should other fileds also be marked as readOnly as well?

In reply to: 560688590 [](ancestors = 560688590)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, if they are set by your service, see here

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to the following rule, I changed the property of our output model object to readOnly and removed the 'required' property.

R2056 RequiredReadOnlyProperties
Category : SDK Error

Applies to : ARM and Data plane OpenAPI(swagger) specs

Output Message: Property '{0}' is a required property. It should not be marked as 'readonly'.

Description: A model property cannot be both readOnly and required. A readOnly property is something that the server sets when returning the model object while required is a property to be set when sending it as a part of the request body.

Why the rule is important: SDK generation fails when this rule is violated.

How to fix the violation: Ensure that the given property is either marked as readonly: true or required but not both.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct, if a customer sets the value, then it cannot be readonly (you can enforce setting the value by specifying required but nothing else), readonly: true is set on properties that your service sets an example is ProvisioningState, this value is set by your service (Running, Provisioning, Succeeded | Failed, etc.) so just add readonly: true to those properties that your service sets.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks just updated the PR.

"readOnly": true,
"description": "Severity contains the severity score for each input point. For a normal point, the severity score is 0. For an anomaly point, the severity score is in (0, 1] that indicates the severity of the anomaly.",
"items": {
"type": "number",
"format": "float",
"readOnly": true,
"x-nullable": false
}
}
}
},
"LastDetectResponse": {
"type": "object",
"required": [
"expectedValue",
"isAnomaly",
"isNegativeAnomaly",
"isPositiveAnomaly",
"lowerMargin",
"period",
"upperMargin",
"suggestedWindow"
],
"properties": {
"period": {
"type": "integer",
"format": "int32",
"readOnly": true,
"description": "Frequency extracted from the series, zero means no recurrent pattern has been found."
},
"suggestedWindow": {
"type": "integer",
"format": "int32",
"readOnly": true,
"description": "Suggested input series points needed for detecting the latest point."
},
"expectedValue": {
"type": "number",
"format": "float",
"readOnly": true,
"description": "Expected value of the latest point."
},
"upperMargin": {
"type": "number",
"format": "float",
"readOnly": true,
"description": "Upper margin of the latest point. UpperMargin is used to calculate upperBoundary, which equals to expectedValue + (100 - marginScale)*upperMargin. If the value of latest point is between upperBoundary and lowerBoundary, it should be treated as normal value. By adjusting marginScale value, anomaly status of latest point can be changed."
},
"lowerMargin": {
"type": "number",
"format": "float",
"readOnly": true,
"description": "Lower margin of the latest point. LowerMargin is used to calculate lowerBoundary, which equals to expectedValue - (100 - marginScale)*lowerMargin. "
},
"isAnomaly": {
"type": "boolean",
"readOnly": true,
"description": "Anomaly status of the latest point, true means the latest point is an anomaly either in negative direction or positive direction."
},
"isNegativeAnomaly": {
"type": "boolean",
"readOnly": true,
"description": "Anomaly status in negative direction of the latest point. True means the latest point is an anomaly and its real value is smaller than the expected one."
},
"isPositiveAnomaly": {
"type": "boolean",
"readOnly": true,
"description": "Anomaly status in positive direction of the latest point. True means the latest point is an anomaly and its real value is larger than the expected one."
},
"severity": {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your service is in preview, but consider marking properties as readOnly where needed, follow this doc.

Copy link
Contributor Author

@guinao guinao Jan 22, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually our service is going to GA. We just have another PR to change 'preview' to 'stable' #12472.

"type": "number",
"format": "float",
"readOnly": true,
"description": "Severity score of the latest point. For a normal point, the severity score is 0. For an anomaly point, the severity score is in (0, 1] that indicates the severity of the anomaly."
}
}
},
Expand Down Expand Up @@ -455,22 +535,19 @@
},
"ChangePointDetectResponse": {
"type": "object",
"required": [
"isChangePoint",
"confidenceScores",
"period"
],
"properties": {
"period": {
"type": "integer",
"format": "int32",
"readOnly": true,
"description": "Frequency extracted from the series, zero means no recurrent pattern has been found."
},
"isChangePoint": {
"type": "array",
"description": "isChangePoint contains change point properties for each input point. True means an anomaly either negative or positive has been detected. The index of the array is consistent with the input series.",
"items": {
"type": "boolean",
"readOnly": true,
"x-nullable": false
}
},
Expand All @@ -480,6 +557,7 @@
"items": {
"type": "number",
"format": "float",
"readOnly": true,
"x-nullable": false
}
}
Expand Down
56 changes: 55 additions & 1 deletion ...tion/cognitiveservices/data-plane/AnomalyDetector/preview/v1.0/examples/EntireDetect.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,11 @@
],
"maxAnomalyRatio": 0.25,
"sensitivity": 95,
"granularity": "monthly"
"granularity": "monthly",
"imputeStrategy": {
"imputeMode": "fixed",
"imputeValue": 850
}
}
},
"responses": {
Expand Down Expand Up @@ -506,6 +510,56 @@
false,
false,
false
],
"severity": [
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.2906614447614368,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0,
0.0
]
}
}
Expand Down
Loading