Licensing and Authorization

GeoAnalytics Engine must be authorized before running any tool or function. You can authorize the module with a GeoAnalytics Engine username and password, a GeoAnalytics Engine access token, 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 go to the GeoAnalytics Engine product page.

You can authorize GeoAnalytics Engine in one of two ways:

  • Call a Python function in a PySpark notebook, shell, or script.
  • Set a property in the Spark configuration.

Authorize using Python

You can authorize GeoAnalytics Engine in a PySpark notebook, the PySpark 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 three options are:

  • Provide a username and password
    Python
    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
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    import geoanalytics
    geoanalytics.auth(username="User1", password="p@ssw0rd")
    
  • Provide a token generated with your username and password
    Python
    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
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    import geoanalytics
    geoanalytics.auth(token="983yr0qjddqewijdlsjdfljfwepwrr45")
    
  • Provide the path to a license file
    Python
    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
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    import geoanalytics
    geoanalytics.auth(license_file="C:\engine\license.ecp")
    
    

Authorize using Spark properties

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

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

    Use dark colors for code blocksCopy
      
    1
    2
    username User1
    password p@ssw0rd
    
  • spark.geoanalytics.auth.token—An access token generated using your username and password with an active subscription to GeoAnalytics Engine.

  • spark.geoanalytics.auth.license.file—The path to a license file.

Verifying 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 user property and the value of that property respectively. The properties returned include:

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

The following property is returned for offline licensing only:

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

The following properties are returned for online licensing only:

  • 'billing_type'—The plan type for online licensing. Options are PayAsYouGo or Prepaid.
  • 'session_usage'—The core hours consumed in the current session in milliseconds. This is the amount charged in milliseconds.

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 online and offline licensing:

  • Online licensing:

    Python
    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
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    
    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
    Before authorization:
    +----+-----+
    |name|value|
    +----+-----+
    +----+-----+
    
    After authorization:
    
    +--------------+-------------+
    |          name|        value|
    +--------------+-------------+
    |session_uptime|        10015|
    |          auth|  token/oauth|
    |         scope|      session|
    |       offline|         true|
    |       metered|         true|
    |    authorized|         true|
    |      username|        User1|
    |  billing_type|   PayAsYouGo|
    | session_usage|            0|
    +--------------+-------------+
    
  • Offline licensing:

    Python
    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
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    import geoanalytics, time
    
    print("Before authorization:")
    geoanalytics.auth_info().show()
    
    geoanalytics.auth(license_file=r"C:\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|  2022-10-19|
    +--------------+------------+
    

Checking usage

For licensing that's metered, you can query the usage history at any time after authorizing using the usage function, geoanalytics.usage(). This function returns a DataFrame where each row represents your user's GeoAnalytics Engine usage during a period of time. The columns ComputeMillis and ComputeHours contain the amount of compute time used during each interval in cpu-milliseconds and cpu-hours respectively. The From and To columns contain the start and end time of each interval. Lastly, the Committed column shows whether or not the usage has been committed to your account. The example below shows what a DataFrame from geoanalytics.usage() might look like.

Python
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
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
import geoanalytics
geoanalytics.auth(username="User1", password="p@ssw0rd")

geoanalytics.usage().show()
Result
Use dark colors for code blocksCopy
            
1
2
3
4
5
6
7
8
9
10
11
12
 +-------------+------------+--------------------+--------------------+---------+
|ComputeMillis|ComputeHours|                From|                  To|Committed|
+-------------+------------+--------------------+--------------------+---------+
|      4719873|      1.3111| 2022-01-10 10:00:00| 2022-01-10 11:00:00|     true|
|       470036|      0.1306| 2022-01-10 11:00:00| 2022-01-10 12:00:00|     true|
|       356497|      0.0990| 2022-01-10 12:00:00| 2022-01-10 13:00:00|     true|
|       295957|      0.0822| 2022-01-10 13:00:00| 2022-01-10 14:00:00|     true|
|            0|      0.0000| 2022-01-10 14:00:00| 2022-01-10 15:00:00|     true|
|            0|      0.0000| 2022-01-10 15:00:00| 2022-01-10 16:00:00|     true|
|            0|      0.0000| 2022-01-10 16:00:00| 2022-01-10 17:00:00|     true|
|          451|      0.0001|2022-01-10 16:02:...|2022-01-10 16:07:...|    false|
+-------------+------------+--------------------+--------------------+---------+

Deauthorization

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

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.