Authorization

GeoAnalytics Engine must be authorized with a valid license before running any tool or function. You can authorize the module with a GeoAnalytics Engine username and password, an API key, or a license file provided by Esri. If the module is not authorized, any tool or function will fail with com.esri.geoanalytics.internal.AuthError: Not authorized. For more information on GeoAnalytics Engine licenses, see Licensing.

You can authorize GeoAnalytics Engine in one of two ways:

• Call geoanalytics.auth() in a PySpark or Scala notebook, shell, or script.
• Set a property in the Spark configuration.

Authorize using geoanalytics.auth()

You can authorize GeoAnalytics Engine in a PySpark or Scala notebook, the Spark shell, or in a script by importing the module and calling the authorization function, geoanalytics.auth(). The function arguments required depend on how you are authorizing the module. The four options are:

• Provide a username and password for an active GeoAnalytics Engine subscription. This securely authorizes GeoAnalytics Engine over the internet using OAuth 2.0.

  PythonPythonScala
  Use dark colors for code blocksCopy

  1
  2
  3
  
  import geoanalytics
  geoanalytics.auth(username="User1", password="p@ssw0rd")

• Provide an API key for an active GeoAnalytics Engine subscription. This also securely authorizes GeoAnalytics Engine over the internet using OAuth 2.0.

  PythonPythonScala
  Use dark colors for code blocksCopy

  1
  2
  3
  
  import geoanalytics
  geoanalytics.auth(api_key="AAPTxy8BH1VEsoebNVZXo8HurN-2tn61d0FQhPnODbRy4BoRx6c9QdIuMnUT...")

• Provide the path to a credentials file containing the username and password for an active GeoAnalytics Engine subscription. Alternatively, the file could contain an API key. In either case, using a credentials file securely authorizes GeoAnalytics Engine over the internet using OAuth 2.0. The file must be accessible to the Spark driver.

  PythonPythonScala
  Use dark colors for code blocksCopy

  1
  2
  3
  
  import geoanalytics
  geoanalytics.auth(cred_file="/engine/creds.txt")

  The following is an example of the contents of a credentials file when using a username and password:

  Use dark colors for code blocksCopy

  1
  2
  username User1
  password p@ssw0rd

  The following is an example of the contents of a credentials file when using an API key:

  Use dark colors for code blocksCopy

  1
  apikey AAPTxy8BH1VEsoebNVZXo8HurN-2tn61d0FQhPnODbRy4BoRx6c9QdIuMnUT...

• Provide the path to a license file for disconnected authorization. The file must be accessible to the Spark driver.

  PythonPythonScala
  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  
  import geoanalytics
  # Authenticate via a local file path accessible from Spark driver
  geoanalytics.auth(license_file="/engine/license.ecp")
  # Authenticate via S3 path
  geoanalytics.auth(license_file="s3://my_bucket/engine/license.ecp")

Authorize using Spark configuration properties

You can also authorize GeoAnalytics Engine in the Spark configuration by setting one of two properties. These properties can be set using command line arguments, a config file, or directly on the SparkContext in a Spark session. For more information see Spark configuration. The two properties are:

• spark.geoanalytics.auth.cred.file—The path to a file containing the username and password for an active GeoAnalytics Engine subscription. For example:

  Use dark colors for code blocksCopy

  1
  2
  username User1
  password p@ssw0rd

  Alternatively, the file can contain an API key for an active GeoAnalytics Engine subscription. For example:

  Use dark colors for code blocksCopy

  1
  apikey AAPTxy8BH1VEsoebNVZXo8HurN-2tn61d0FQhPnODbRy4BoRx6c9QdIuMnUT...

  In either case, the file must be accessible to the Spark driver in order to securely authorize GeoAnalytics Engine over the internet using OAuth 2.0.

• spark.geoanalytics.auth.license.file—The path to a license file for disconnected authorization. The file must be accessible to the Spark driver.

Verify authorization

You can verify that you are correctly authorized to use GeoAnalytics Engine by running any SQL function or tool, or by calling the authorization info function, geoanalytics.auth_info(). This function returns a DataFrame with two columns, name and value, which represent the name of a usage property and the value of that property respectively. The properties returned include:

• 'session_uptime'—The amount of time in milliseconds that GeoAnalytics Engine has been authorized in the current session.
• 'auth'—The type of authorization currently in use. Options are token/oauth (when authorizing with a username/password), token/apikey (when authorizing with an API key) or license/file (when authorizing with a license file).
• 'scope'—The scope of the current authorization.
• 'offline'—False if the module is connected for usage reporting, otherwise True.
• 'metered'—True if usage is being measured, otherwise False. Usage is measured in compute units per millisecond. Usage is only metered for connected licensing.
• 'authorized'—True if the module is correctly authorized and ready to use.

The following property is returned for disconnected licensing only:

• 'expires'—The date the disconnected license file expires.

The following properties are returned for connected licensing only:

• 'billing_type'—The plan type for connected licensing.
• 'available_hours'—The remaining compute unit-hours (also known as core-hours) available in your subscription.
• 'session_usage'—The compute unit-milliseconds consumed in the current session.

If the module is not authorized, geoanalytics.auth_info() will return an empty DataFrame. The code snippet below shows an example of what the DataFrame returned from geoanalytics.auth_info() might look like before and 10 seconds after authorization for connected and disconnected licensing:

• Connected authorization:

  PythonPythonScala
  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  
  import geoanalytics, time
  
  print("Before authorization:")
  geoanalytics.auth_info().show()
  
  geoanalytics.auth(username="User1", password="p@ssw0rd")
  time.sleep(10)
  
  print("After authorization:")
  geoanalytics.auth_info().show()
  Result

  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  Before authorization:
  +----+-----+
  |name|value|
  +----+-----+
  +----+-----+
  
  After authorization:
  
  +---------------+-----------+
  |           name|      value|
  +---------------+-----------+
  | session_uptime|      10015|
  |           auth|token/oauth|
  |          scope|    session|
  |        offline|      false|
  |        metered|       true|
  |     authorized|       true|
  |       username|    gae_dev|
  |   billing_type|    Prepaid|
  |available_hours|    3718.87|
  |  session_usage|          0|
  +---------------+-----------+

• Disconnected authorization:

  PythonPythonScala
  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  
  import geoanalytics, time
  
  print("Before authorization:")
  geoanalytics.auth_info().show()
  
  geoanalytics.auth(license_file=r"/engine/license.ecp")
  time.sleep(10)
  
  print("After authorization:")
  geoanalytics.auth_info().show()
  Result

  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  Before authorization:
  +----+-----+
  |name|value|
  +----+-----+
  +----+-----+
  
  After authorization:
  
  +--------------+------------+
  |          name|       value|
  +--------------+------------+
  |session_uptime|       10015|
  |          auth|license/file|
  |         scope|     session|
  |       offline|        true|
  |       metered|       false|
  |    authorized|        true|
  |       expires|  20xx-10-19|
  +--------------+------------+

Deauthorization

Once you authorize GeoAnalytics Engine, it will remain authorized until the Spark session is ended or until you call the deauthorization function.

1
2

geoanalytics.deauth()