Long-running Operations

The Submission API is asynchronous and returns a long-running operation. The operation might not be completed when the method returns a response.

Get an operation status

The following shows how to poll an operation's status.

Call the GET method for the Operations type.

Before using any of the request data, make the following replacements:

  • project-number: your Google Cloud project number
  • operation-id: your operation ID

HTTP method and URL: 

GET https://webrisk.googleapis.com/v1/projects/project-number/operations/operation-id

To send your request, choose one of these options:

curl

Execute the following command: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://webrisk.googleapis.com/v1/projects/project-number/operations/operation-id"

PowerShell

Execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://webrisk.googleapis.com/v1/projects/project-number/operations/operation-id" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/project-number/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.webrisk.v1.SubmitUriMetadata",
    "state": "RUNNING"
  }
  "done": false,
  ...
}

Understanding Operation Status

The metadata.state field in the response indicates the current status of the submission. When the operation is completed, the state field in the SubmitUriMetadata is updated. The possible states are the following:

  • SUCCEEDED: Indicates that the submitted URL was added to the Safe Browsing Blocklist.
  • CLOSED: Indicates that the submitted URL was not added to the Safe Browsing blocklist because it was not found to violate Safe Browsing policies.
  • RUNNING: Indicates that the submission is still being processed.

Understanding CLOSED reasons

When the operation state is CLOSED, the SubmitUriMetadata might include a closed_reason field. This field provides additional context on why the submission was closed without the URL being added to a blocklist.

The possible values for closed_reason are the following:

  • CLOSED_REASON_UNSPECIFIED: The reason is not specified.
  • NO_THREAT_DETECTED:
    • Description: The submitted URL was successfully analyzed and was not found to contain malicious content. This indicates that, based on our analysis, the URL does not meet the criteria for blocklisting.
    • Recommended User Action: No further action is typically needed for this URL, as it was not found to be a threat. Don't repeatedly resubmit unless the content changes and new evidence of malicious activity emerges.
  • HOST_UNRESOLVABLE:
    • Description: We could not complete the analysis because the URL's hostname couldn't be resolved by DNS. This often means the website is down, the domain no longer exists, or there was a temporary DNS issue. We cannot add inactive or placeholder URLs to the blocklist.
    • Recommended User Action:
      • Verify the URL: Ensure the hostname is correct and the website is active and publicly accessible.
      • Resubmit: You may resubmit the URL later if you confirm the site is active.
  • CONTENT_UNREACHABLE:
    • Description: Analysis could not be completed because the website's content couldn't be reached. This can happen for several reasons, such as:
      • The web page no longer exists (this is a "404 Not Found" error).
      • The website's server encountered an error (this is a "5xx Server Error").
      • The website might be showing different content to our analysis system than it would to a regular visitor (this is cloaking), preventing a full assessment.
    • Recommended User Action:
      • Check Accessibility: Confirm that the malicious content is reachable. Note that some sites may only show malicious content under specific conditions (this is certain geographic locations, devices, or browsers).
      • Provide More Context: If the URL is accessible under specific conditions, resubmit it. Use the ThreatDiscovery fields in the SubmitUriRequest to provide additional details, such as the region and platform where the threat was observed. This information can increase the likelihood of a successful analysis.