Skip to content

Commit bee4b07

Browse files
busunkim96busunkim96
authored
All: Add docs job to publish to googleapis.dev. (#8464)
1 parent 6089ed5 commit bee4b07

16 files changed

+815
-0
lines changed

‎.repo-metadata.json

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"name": "google-api-core",
3+
"name_pretty": "Google API client core library",
4+
"client_documentation": "https://googleapis.dev/python/google-api-core/latest",
5+
"release_level": "ga",
6+
"language": "python",
7+
"repo": "googleapis/google-cloud-python",
8+
"distribution_name": "google-api-core"
9+
}

‎docs/auth.rst

Lines changed: 301 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
1+
Authentication
2+
**************
3+
4+
.. _Overview:
5+
6+
Overview
7+
========
8+
9+
* **If you're running in Compute Engine or App Engine**,
10+
authentication should "just work".
11+
12+
* **If you're developing locally**,
13+
the easiest way to authenticate is using the `Google Cloud SDK`_:
14+
15+
.. code-block:: bash
16+
17+
$ gcloud auth application-default login
18+
19+
Note that this command generates credentials for client libraries. To authenticate the CLI itself, use:
20+
21+
.. code-block:: bash
22+
23+
$ gcloud auth login
24+
25+
Previously, ``gcloud auth login`` was used for both use cases. If
26+
your ``gcloud`` installation does not support the new command,
27+
please update it:
28+
29+
.. code-block:: bash
30+
31+
$ gcloud components update
32+
33+
.. _Google Cloud SDK: http://cloud.google.com/sdk
34+
35+
36+
* **If you're running your application elsewhere**,
37+
you should download a `service account`_ JSON keyfile
38+
and point to it using an environment variable:
39+
40+
.. code-block:: bash
41+
42+
$ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"
43+
44+
.. _service account: https://cloud.google.com/storage/docs/authentication#generating-a-private-key
45+
46+
Client-Provided Authentication
47+
==============================
48+
49+
Every package uses a :class:`Client <google.cloud.client.Client>`
50+
as a base for interacting with an API.
51+
For example:
52+
53+
.. code-block:: python
54+
55+
from google.cloud import datastore
56+
client = datastore.Client()
57+
58+
Passing no arguments at all will "just work" if you've followed the
59+
instructions in the :ref:`Overview`.
60+
The credentials are inferred from your local environment by using
61+
Google `Application Default Credentials`_.
62+
63+
.. _Application Default Credentials: https://developers.google.com/identity/protocols/application-default-credentials
64+
65+
.. _Precedence:
66+
67+
Credential Discovery Precedence
68+
-------------------------------
69+
70+
When loading the `Application Default Credentials`_,
71+
the library will check for credentials in your environment by following the
72+
precedence outlined by :func:`google.auth.default`.
73+
74+
Explicit Credentials
75+
====================
76+
77+
The Application Default Credentials discussed above can be useful
78+
if your code needs to run in many different environments or
79+
if you just don't want authentication to be a focus in your code.
80+
81+
However, you may want to be explicit because
82+
83+
* your code will only run in one place
84+
* you may have code which needs to be run as a specific service account
85+
every time (rather than with the locally inferred credentials)
86+
* you may want to use two separate accounts to simultaneously access data
87+
from different projects
88+
89+
In these situations, you can create an explicit
90+
:class:`~google.auth.credentials.Credentials` object suited to your environment.
91+
After creation, you can pass it directly to a :class:`Client <google.cloud.client.Client>`:
92+
93+
.. code:: python
94+
95+
client = Client(credentials=credentials)
96+
97+
.. tip::
98+
To create a credentials object, follow the `google-auth-guide`_.
99+
100+
.. _google-auth-guide: https://google-auth.readthedocs.io/en/latest/user-guide.html#service-account-private-key-files
101+
102+
103+
Google App Engine Environment
104+
-----------------------------
105+
106+
To create
107+
:class:`credentials <google.auth.app_engine.Credentials>`
108+
just for Google App Engine:
109+
110+
.. code:: python
111+
112+
from google.auth import app_engine
113+
credentials = app_engine.Credentials()
114+
115+
Google Compute Engine Environment
116+
---------------------------------
117+
118+
To create
119+
:class:`credentials <google.auth.compute_engine.Credentials>`
120+
just for Google Compute Engine:
121+
122+
.. code:: python
123+
124+
from google.auth import compute_engine
125+
credentials = compute_engine.Credentials()
126+
127+
Service Accounts
128+
----------------
129+
130+
A `service account`_ is stored in a JSON keyfile.
131+
132+
The
133+
:meth:`from_service_account_json() <google.cloud.client.Client.from_service_account_json>`
134+
factory can be used to create a :class:`Client <google.cloud.client.Client>` with
135+
service account credentials.
136+
137+
For example, with a JSON keyfile:
138+
139+
.. code:: python
140+
141+
client = Client.from_service_account_json('/path/to/keyfile.json')
142+
143+
.. tip::
144+
145+
Previously the Google Cloud Console would issue a PKCS12/P12 key for your
146+
service account. This library does not support that key format. You can
147+
generate a new JSON key for the same service account from the console.
148+
149+
User Accounts (3-legged OAuth 2.0) with a refresh token
150+
-------------------------------------------------------
151+
152+
The majority of cases are intended to authenticate machines or
153+
workers rather than actual user accounts. However, it's also
154+
possible to call Google Cloud APIs with a user account via
155+
`OAuth 2.0`_.
156+
157+
.. _OAuth 2.0: https://developers.google.com/identity/protocols/OAuth2
158+
159+
.. tip::
160+
161+
A production application should **use a service account**,
162+
but you may wish to use your own personal user account when first
163+
getting started with the ``google-cloud-python`` library.
164+
165+
The simplest way to use credentials from a user account is via
166+
Application Default Credentials using ``gcloud auth login``
167+
(as mentioned above) and :func:`google.auth.default`:
168+
169+
.. code:: python
170+
171+
import google.auth
172+
173+
credentials, project = google.auth.default()
174+
175+
This will still follow the :ref:`precedence <Precedence>`
176+
described above,
177+
so be sure none of the other possible environments conflict
178+
with your user provided credentials.
179+
180+
Advanced users of `oauth2client`_ can also use custom flows to
181+
create credentials using `client secrets`_ or using a
182+
`webserver flow`_.
183+
After creation, :class:`Credentials <oauth2client.client.Credentials>`
184+
can be serialized with
185+
:meth:`to_json() <oauth2client.client.Credentials.to_json>`
186+
and stored in a file and then and deserialized with
187+
:meth:`from_json() <oauth2client.client.Credentials.from_json>`. In order
188+
to use ``oauth2client``'s credentials with this library, you'll need to
189+
`convert them`_.
190+
191+
.. _oauth2client: https://github.com/Google/oauth2client.
192+
.. _client secrets: https://developers.google.com/api-client-library/python/guide/aaa_oauth#flow_from_clientsecrets
193+
.. _webserver flow: https://developers.google.com/api-client-library/python/guide/aaa_oauth#OAuth2WebServerFlow
194+
.. _convert them: http://google-auth.readthedocs.io/en/stable/user-guide.html#user-credentials
195+
196+
Troubleshooting
197+
===============
198+
199+
Setting up a Service Account
200+
----------------------------
201+
202+
If your application is not running on Google Compute Engine,
203+
you need a `Google Developers Service Account`_.
204+
205+
#. Visit the `Google Developers Console`_.
206+
207+
#. Create a new project or click on an existing project.
208+
209+
#. Navigate to **APIs & auth** > **APIs** and enable the APIs
210+
that your application requires.
211+
212+
.. raw:: html
213+
214+
<img src="https://raw.githubusercontent.com/GoogleCloudPlatform/google-cloud-common/master/authentication/enable-apis.png"/>
215+
216+
.. note::
217+
218+
You may need to enable billing in order to use these services.
219+
220+
* **BigQuery**
221+
222+
* BigQuery API
223+
224+
* **Datastore**
225+
226+
* Google Cloud Datastore API
227+
228+
* **Pub/Sub**
229+
230+
* Google Cloud Pub/Sub
231+
232+
* **Storage**
233+
234+
* Google Cloud Storage
235+
* Google Cloud Storage JSON API
236+
237+
#. Navigate to **APIs & auth** > **Credentials**.
238+
239+
You should see a screen like one of the following:
240+
241+
.. raw:: html
242+
243+
<img src="https://raw.githubusercontent.com/GoogleCloudPlatform/google-cloud-common/master/authentication/create-new-service-account.png">
244+
245+
.. raw:: html
246+
247+
<img src="https://raw.githubusercontent.com/GoogleCloudPlatform/google-cloud-common/master/authentication/create-new-service-account-existing-keys.png">
248+
249+
Find the "Add credentials" drop down and select "Service account" to be
250+
guided through downloading a new JSON keyfile.
251+
252+
If you want to re-use an existing service account,
253+
you can easily generate a new keyfile.
254+
Just select the account you wish to re-use,
255+
and click **Generate new JSON key**:
256+
257+
.. raw:: html
258+
259+
<img src="https://raw.githubusercontent.com/GoogleCloudPlatform/google-cloud-common/master/authentication/reuse-service-account.png">
260+
261+
.. _Google Developers Console: https://console.developers.google.com/project
262+
.. _Google Developers Service Account: https://developers.google.com/accounts/docs/OAuth2ServiceAccount
263+
264+
Using Google Compute Engine
265+
---------------------------
266+
267+
If your code is running on Google Compute Engine,
268+
using the inferred Google `Application Default Credentials`_
269+
will be sufficient for retrieving credentials.
270+
271+
However, by default your credentials may not grant you
272+
access to the services you intend to use.
273+
Be sure when you `set up the GCE instance`_,
274+
you add the correct scopes for the APIs you want to access:
275+
276+
* **All APIs**
277+
278+
* ``https://www.googleapis.com/auth/cloud-platform``
279+
* ``https://www.googleapis.com/auth/cloud-platform.read-only``
280+
281+
* **BigQuery**
282+
283+
* ``https://www.googleapis.com/auth/bigquery``
284+
* ``https://www.googleapis.com/auth/bigquery.insertdata``
285+
286+
* **Datastore**
287+
288+
* ``https://www.googleapis.com/auth/datastore``
289+
* ``https://www.googleapis.com/auth/userinfo.email``
290+
291+
* **Pub/Sub**
292+
293+
* ``https://www.googleapis.com/auth/pubsub``
294+
295+
* **Storage**
296+
297+
* ``https://www.googleapis.com/auth/devstorage.full_control``
298+
* ``https://www.googleapis.com/auth/devstorage.read_only``
299+
* ``https://www.googleapis.com/auth/devstorage.read_write``
300+
301+
.. _set up the GCE instance: https://cloud.google.com/compute/docs/authentication#using

‎docs/changelog.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../CHANGELOG.md

‎docs/client_info.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Client Information Helpers
2+
==========================
3+
4+
.. automodule:: google.api_core.client_info
5+
:members:
6+
:show-inheritance:
7+
8+
.. automodule:: google.api_core.gapic_v1.client_info
9+
:members:
10+
:show-inheritance:
11+

0 commit comments

Comments
 (0)