Utilizzare le chiavi API per accedere alle API

Questa pagina descrive come utilizzare le chiavi API per accedere alle API e ai servizi Google Cloud che accettano le chiavi API.

Non tutte le API Google Cloud accettano chiavi API per autorizzare l'utilizzo. Esamina la documentazione del servizio o dell'API che vuoi utilizzare per stabilire se accetta le chiavi API.

Per informazioni su come creare e gestire le chiavi API, inclusa la limitazione delle chiavi API, consulta Gestire le chiavi API.

Per informazioni sull'utilizzo delle chiavi API con Google Maps Platform, consulta la documentazione di Google Maps Platform. Per ulteriori informazioni sull'API API Keys, consulta la documentazione dell'API API Keys.

Utilizzo di una chiave API con REST

Puoi passare la chiave API a una chiamata API REST come parametro di query con il seguente formato. Sostituisci API_KEY con la stringa della chiave della tua chiave API.

Ad esempio, per passare una chiave API per una richiesta dell'API Cloud Natural Language per documents.analyzeEntities:

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

In alternativa, puoi utilizzare l'intestazione x-goog-api-key per passare la chiave. Questa intestazione deve essere utilizzata con le richieste gRPC.

curl -X POST \
    -H "X-goog-api-key: API_KEY" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://translation.googleapis.com/language/translate/v2"

Utilizzo di una chiave API con le librerie client

Il supporto della libreria client per le chiavi API è specifico per il linguaggio.

Questo esempio utilizza l'API Cloud Natural Language, che supporta le chiavi API per l'autenticazione, per dimostrare come fornire una chiave API alla libreria.

C#

Per eseguire questo esempio, devi installare la libreria client Natural Language.


using Google.Cloud.Language.V1;
using System;

public class UseApiKeySample
{
    public void AnalyzeSentiment(string apiKey)
    {
        LanguageServiceClient client = new LanguageServiceClientBuilder
        {
            ApiKey = apiKey
        }.Build();

        string text = "Hello, world!";

        AnalyzeSentimentResponse response = client.AnalyzeSentiment(Document.FromPlainText(text));
        Console.WriteLine($"Text: {text}");
        Sentiment sentiment = response.DocumentSentiment;
        Console.WriteLine($"Sentiment: {sentiment.Score}, {sentiment.Magnitude}");
        Console.WriteLine("Successfully authenticated using the API key");
    }
}

C++

Per eseguire questo esempio, devi installare la libreria client Natural Language.

#include "google/cloud/language/v1/language_client.h"
#include "google/cloud/credentials.h"
#include "google/cloud/options.h"

void AuthenticateWithApiKey(std::vector<std::string> const& argv) {
  if (argv.size() != 2) {
    throw google::cloud::testing_util::Usage{
        "authenticate-with-api-key <project-id> <api-key>"};
  }
  namespace gc = ::google::cloud;
  auto options = gc::Options{}.set<gc::UnifiedCredentialsOption>(
      gc::MakeApiKeyCredentials(argv[1]));
  auto client = gc::language_v1::LanguageServiceClient(
      gc::language_v1::MakeLanguageServiceConnection(options));

  auto constexpr kText = "Hello, world!";

  google::cloud::language::v1::Document d;
  d.set_content(kText);
  d.set_type(google::cloud::language::v1::Document::PLAIN_TEXT);

  auto response = client.AnalyzeSentiment(d, {});
  if (!response) throw std::move(response.status());
  auto const& sentiment = response->document_sentiment();
  std::cout << "Text: " << kText << "\n";
  std::cout << "Sentiment: " << sentiment.score() << ", "
            << sentiment.magnitude() << "\n";
  std::cout << "Successfully authenticated using the API key\n";
}

Vai

Per eseguire questo esempio, devi installare la libreria client Natural Language.

import (
	"context"
	"fmt"
	"io"

	language "cloud.google.com/go/language/apiv1"
	"cloud.google.com/go/language/apiv1/languagepb"
	"google.golang.org/api/option"
)

// authenticateWithAPIKey authenticates with an API key for Google Language
// service.
func authenticateWithAPIKey(w io.Writer, apiKey string) error {
	// apiKey := "api-key-string"

	ctx := context.Background()

	// Initialize the Language Service client and set the API key.
	client, err := language.NewClient(ctx, option.WithAPIKey(apiKey))
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	text := "Hello, world!"
	// Make a request to analyze the sentiment of the text.
	res, err := client.AnalyzeSentiment(ctx, &languagepb.AnalyzeSentimentRequest{
		Document: &languagepb.Document{
			Source: &languagepb.Document_Content{
				Content: text,
			},
			Type: languagepb.Document_PLAIN_TEXT,
		},
	})
	if err != nil {
		return fmt.Errorf("AnalyzeSentiment: %w", err)
	}

	fmt.Fprintf(w, "Text: %s\n", text)
	fmt.Fprintf(w, "Sentiment score: %v\n", res.DocumentSentiment.Score)
	fmt.Fprintln(w, "Successfully authenticated using the API key.")

	return nil
}

Java

Per eseguire questo esempio, devi installare la libreria client Natural Language.

import com.google.cloud.language.v2.AnalyzeSentimentResponse;
import com.google.cloud.language.v2.Document;
import com.google.cloud.language.v2.LanguageServiceClient;
import com.google.cloud.language.v2.LanguageServiceSettings;
import java.io.IOException;

  static String authenticateUsingApiKey(String apiKey) throws IOException {
    LanguageServiceSettings settings =
        LanguageServiceSettings.newBuilder().setApiKey(apiKey).build();
    try (LanguageServiceClient client = LanguageServiceClient.create(settings)) {
      Document document =
          Document.newBuilder()
              .setContent("Hello World!")
              .setType(Document.Type.PLAIN_TEXT)
              .build();

      AnalyzeSentimentResponse actualResponse = client.analyzeSentiment(document);

      return actualResponse.getDocumentSentiment().toString();
    }
  }

Node.js

Per eseguire questo esempio, devi installare la libreria client Natural Language.


const {
  v1: {LanguageServiceClient},
} = require('@google-cloud/language');

/**
 * Authenticates with an API key for Google Language service.
 *
 * @param {string} apiKey An API Key to use
 */
async function authenticateWithAPIKey(apiKey) {
  const language = new LanguageServiceClient({apiKey});

  // Alternatively:
  // const auth = new GoogleAuth({apiKey});
  // const {GoogleAuth} = require('google-auth-library');
  // const language = new LanguageServiceClient({auth});

  const text = 'Hello, world!';

  const [response] = await language.analyzeSentiment({
    document: {
      content: text,
      type: 'PLAIN_TEXT',
    },
  });

  console.log(`Text: ${text}`);
  console.log(
    `Sentiment: ${response.documentSentiment.score}, ${response.documentSentiment.magnitude}`
  );
  console.log('Successfully authenticated using the API key');
}

authenticateWithAPIKey();

PHP

Per eseguire questo esempio, devi installare la libreria client Natural Language.

namespace Google\Cloud\Samples\Auth;

use Google\ApiCore\ApiException;
use Google\ApiCore\PagedListResponse;
use Google\Cloud\Vision\V1\Client\ProductSearchClient;
use Google\Cloud\Vision\V1\ListProductsRequest;
use Google\Cloud\Vision\V1\Product;

/**
 * Authenticate to a cloud API using an API key explicitly.
 * Note: This only works for APIs with support for API keys.
 *
 * @param string $projectId     The Google Cloud project ID.
 * @param string $location      The location name.
 * @param string $apiKey        The API key.
 */
function auth_cloud_apikey(string $projectId, string $location, string $apiKey): void
{
    $formattedParent = ProductSearchClient::locationName($projectId, $location);

    // Create a client.
    $productSearchClient = new ProductSearchClient([
        'apiKey' => $apiKey,
    ]);

    // Prepare the request message.
    $request = (new ListProductsRequest())
        ->setParent($formattedParent);

    // Call the API and handle any network failures.
    try {
        /** @var PagedListResponse $response */
        $response = $productSearchClient->listProducts($request);

        /** @var Product $element */
        foreach ($response as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

Python

Per eseguire questo esempio, devi installare la libreria client Natural Language.


from google.cloud import language_v1


def authenticate_with_api_key(api_key_string: str) -> None:
    """
    Authenticates with an API key for Google Language service.

    TODO(Developer): Replace this variable before running the sample.

    Args:
        api_key_string: The API key to authenticate to the service.
    """

    # Initialize the Language Service client and set the API key
    client = language_v1.LanguageServiceClient(
        client_options={"api_key": api_key_string}
    )

    text = "Hello, world!"
    document = language_v1.Document(
        content=text, type_=language_v1.Document.Type.PLAIN_TEXT
    )

    # Make a request to analyze the sentiment of the text.
    sentiment = client.analyze_sentiment(
        request={"document": document}
    ).document_sentiment

    print(f"Text: {text}")
    print(f"Sentiment: {sentiment.score}, {sentiment.magnitude}")
    print("Successfully authenticated using the API key")

Quando utilizzi le chiavi API nelle tue applicazioni, assicurati che vengano protette sia durante lo stoccaggio sia durante la trasmissione. L'esposizione pubblica delle chiavi API può comportare addebiti imprevisti sul tuo account. Per ulteriori informazioni, consulta le best practice per la gestione delle chiavi API.

Passaggi successivi