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, or a license file provided by Esri. If the module is
not authorized, any tool or function will fail with com.esri.geoanalytics.internal.
. For
more information on GeoAnalytics Engine licenses, see Licensing.
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 two 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.
Python
Use dark colors for code blocks Copy import geoanalytics geoanalytics.auth(username="User1", password="p@ssw0rd")
- Provide the path to a license file for disconnected authorization. The file must be accessible to the
Spark driver.
Python
Use dark colors for code blocks Copy import geoanalytics geoanalytics.auth(license_file="/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 for an active GeoAnalytics Engine subscription. The file must be accessible to the Spark driver. This securely authorizes GeoAnalytics Engine over the internet using OAuth 2.0. For example:Use dark colors for code blocks Copy username User1 password p@ssw0rd
-
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
. 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
—The amount of time in milliseconds that GeoAnalytics Engine has been authorized in the current session._uptime' 'auth'
—The type of authorization currently in use. Options aretoken/oauth
orlicense/file
.'scope'
—The scope of the current authorization.'offline'
—False if the module is connected for usage time reporting, otherwise True.'metered'
—True if usage time is being measured. 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
—The plan type for connected licensing._type' 'session
—The compute unit-milliseconds consumed in the current session._usage'
If the module is not authorized, geoanalytics.auth
will return an empty DataFrame. The code snippet below
shows an example of what the DataFrame returned from geoanalytics.auth
might look like before and 10 seconds after
authorization for connected and disconnected licensing:
-
Connected authorization:
PythonUse dark colors for code blocks Copy 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()
ResultUse dark colors for code blocks Copy 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| +--------------+-------------+
-
Disconnected authorization:
PythonUse dark colors for code blocks Copy 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()
ResultUse dark colors for code blocks Copy 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| +--------------+------------+
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()
.